*briofita.txt* Companion help to Briofita, a customizable dark GUI colorscheme

+--------------+-------------------------------------------------------------+
|   *briofita*   | `Briofita`: a complex, (somewhat-)dark background  Vim  GUI   |
|              | colorscheme with selectable user options designed for easy  |
|              | "rotation" or "cycling" of optins by Vim plugins.           |
|              +-------------------------------------------------------------+
|              | `briofita-support`: A companion  Vim plugin  it  shows how  a |
|              | plugin can interact with the colorscheme.   Its extensively |
|              | tested functionalities, operations  and  menus  make it  a  |
|              | handy tool to set the colorscheme parameters.               |
|              +-------------------------------------------------------------+
|              | `Helpfile`  This file. This is a Vim helpfile companion to    |
|              | the Briofita colorscheme. It tells about its operation      |
|              | and has details about how to set its parameters in order    |
|              | to customize it.                                            |
|              +-------------------------------------------------------------+
|              | `Version`   v3.1.0  (view the release notes at the end)       |
|              | Author:   Sergio Nobre (sergio.o.nobre at gmail dot com)    |
|              | Licence:  The VIM LICENCE applies to Briofita, just change  |
|              |           the term "Vim" to "Briofita" in its text          |
|              |           (the Vim licence is in the help: ":help license").|
+--------------+-------------------------------------------------------------+


==============================================================================
TABLE OF CONTENTS                                         *briofita-TOC*    {{{1
==============================================================================

 About Briofita .............................. |briofita-about|
 Installation ................................ |briofita-installation|
 Colorscheme customization ................... |briofita-customization|
 Options list ................................ |briofita-options-list|
 Tabpage local settings ...................... |briofita-local-settings|
 Plugin ...................................... |briofita-plugin|
       Menus ................................. |briofita-menus|
       Global functions ...................... |briofita-functions|
       Commands and maps ..................... |briofita-cmds-maps|
 Performance ................................. |briofita-performance|
 Syntax coverage ............................. |briofita-coverage|
 Useful Vim Help entries for newbies ......... |briofita-vimhelp|
 Issues ...................................... |briofita-known-issues|
 History ..................................... |briofita-history|
 TODO ........................................ |briofita-todo|
 NOTES ....................................... |briofita-notes|


==============================================================================

ABOUT BRIOFITA                                            *briofita-about*  {{{1


`Briofita` is basically composed of
		(1) a complex GUI colorscheme,
		(2) a plugin that makes it easy for the user to drive the colorscheme
			parameters ("briofita-support.vim"), and
		(3) this Vim help file ("briofita.txt").

It can be downloaded from its Vim online page:
        http://www.vim.org/scripts/script.php?script_id=4136.

The normal colorscheme background style is of a shaded dark-green color (by
default). The only exception is given by one of the options of the Normal
dict key, which has black background.

Briofita uses high contrast in a few syntax items. It gives higher priority to
user's visual comfort within each filetype editing session, consequently, it
does not try to enforce equal display of different filetypes' items that
happen to have similar names (although many of such syntax items get similar
highlights).

The colorscheme was designed to fit study, research and work needs. (It is not
recommended to color blinded people: it has elements highlighted in red.)

Due to the unusually high number of syntax highlights it implements and to
its customization options, this is not a minimalist colorscheme, and, at the
time of this release it is not recommended for use in systems which are low in
memory or have older CPUs (this limitation is likely going to be short-lived,
given the current pace of hardware changes...).

The colorscheme can be used without any customization; there are proper
defaults for the typical user.

The colorscheme does not depend on the companion plugin (which is recommended
because it is a handy GUI tool for setting the colorscheme options and for
easily changing them). The plugin does not have to be installed for the
colorscheme to function; on the other hand, most of the plugin's functionality
requires that the colorscheme be installed and active.

History~
Originally this colorscheme was just a tweaked version of `Moss` (vimscript
#2779), with few changes for personal preferences; inspired by some favorite
colorschemes, other features were added along the time; then it was
restructured to use a color dictionary similar to the one used by the
`Distinguished` colorscheme (vimscript #3529). Later, several highlights
for the author's favorite plugins have been added.

Operating Systems~
Development is currently done under GNU/Linux. The following remarks apply:

Colorscheme: There is no operating-system specific command in the colorscheme.
It should be `fully` functional under non-GNU/Linux operating systems.

Plugin: It is supposed that `most` of its functionality is available under
non-GNU/Linux OSs.

Please email the author, telling about your experiments with non-GNU/Linux
OSs so that improvements can be provided in future releases.

                                                                  |briofita-TOC|

==============================================================================

INSTALLATION                                       *briofita-installation*  {{{1


Briofita is currently made available first in the Vim online site.
It is released as a packed file (zip).

Manual installation for non-Pathogen users~

Just unpack it and move the files from the "colors", "doc" and "plugin"
directories into the respective directories of your ".vim" directory.
And do :helptags.

Manual installation for Pathogen users~

In case you use Pathogen (or similar bundle-based plugins) create a
".vim/bundle/briofita" directory and move the directory tree of the
unpacked file into it. (If you do not want the plugin, just delete the "plugin"
directory from the unzipped directory tree.)
Proceed by doing ":Helptags".

Things to do after installing Briofita~

Read the hints about using Briofita in the help file:
>
			:help briofita
<
Edit your ".gvimrc" file to add the parameters you like.

Test it:

Open another instance of GUI Vim and execute the following
command:
>
			:color briofita
<
If you have installed the TabPageColorScheme plugin, the above command can be
replaced by the below one (this makes the colorscheme active for the current
tabpage):
>
 			:Tcolorscheme briofita
<
To have the colorscheme started at Vim start-up just put one of the above commands
in your ".gvimrc" (currently Briofita is a GUI-only colorscheme).

These commands may be manually executed via briofita-support plugin menu, if
you have installed the plugin. Just navigate through the menu until you find
those entries that show the above commands. Clicking one of them you reload
Briofita by the corresponding method.

Partial Installation~
The colorscheme does not depend on the plugin.
If you want the colorscheme but not the plugin: >
	Do not copy the plugin into the "plugin" directory; or, if it is already
	there due to a bundled install, just delete your
	          ~/.vim/bundle/briofita/plugin
	directory.
<

Uninstallation~
To uninstall Briofita, just delete the above sources from the "colors", "doc"
and "plugin" directories.

------------------------------------------------------------------------------
Recommended Tabpagecolorscheme plugin~

The author uses and recommends the Vim plugin "tabpagecolorscheme".
It makes your tabpages "remember" their colorscheme.  Get it from the Vim site:

http://www.vim.org/scripts/script.php?script_id=3358.

This plugin allows a different colorscheme to be active in each tabpage.
The Briofita companion plugin, briofita-support, has an example of calling a
command of this plugin. (Briofita can be normally used without it.)

When using the plugin you re-source the colorscheme by clicking on another
tabpage and then back to the original tab.

Recommended tlib library plugin~

The companion plugin displays its messages either via ":echo*" commands or
via GUI dialogs, which are visually better. The latter use the tlib library,
if available. You may install it easily, just search "tlib" on the Vim
Online site (or on github).

Other Tabpage Colorscheme Plugins~
Until now Briofita has been tested only with the recommended plugin.
There might be some other Vim plugin that performs like the recommended one.
In case you research and find one, Let me know of your experiments: my email
is on this helpfile heading.

Interaction with Common Statusline Plugins~
The statusline plugin you use (if any) might not be aware of tabpage-local
colorschemes. In case you try and it does not work as expected, just disable
the Briofita statusline option (it is what we call a "boolean" option).

                                                                  |briofita-TOC|


==============================================================================

COLORSCHEME CUSTOMIZATION                         *briofita-customization*  {{{1


Briofita comes with default settings for common user's needs, but
the user may choose what he/she prefers, among some options. The
chosen options can be saved in a Vimscript file to be sourced via
.gvimrc. Or even included in .gvimrc. This may be regarded
as a simplified "favorite" feature. (One of the plugin's menus
make it easy to "dump" the options into a new tabpage buffer.)

There are two option types. Global options are applicable to any tabpage.
Local options can be different from one tabpage to another. Currently
the second type is implemented only for the CursorLine highlight (and
optionally coupled CursorColumn highlight).

Options are provided to customize the way the syntax items are displayed.
They provide alternative displays for selected syntax items.

The options (which we also call "parameters") are specified via integers,
being zero the default. These numeric parameters were designed to enable user
functions or plugins to easily change them by "option rotation" (which we also
call "cycling") but can be manually set via command-line.

For practical reasons, in some cases more than one Vim highlight gets
associated to one Briofita option, so that cycling the values of this one
effects a change in that group of Vim highlights. Each time you change the
numeric value of a grouped option you get a different visual effect on each
highlight item in the group. We call such grouped items "linked highlights",
"coupled highlights" or "connected highlights".

Most of the options are named after one of the related highlights they implement,
regarded as the "main" syntax item. But few of the options have only the main
item. Most have unrelated items which have got grouped. You may
get a list of the grouped items via one of the plugin menu entries.


Changeable Parameters (Options)~

Global options can be set by the user by assigning numerical values to the >
	   g:briofita_parms
<
dictionary. Tabpage-local option "cursorline" can be set by by assigning
numerical values to the >
	   t:briofita_cursorline
<
variable, provided the global "localcursorline" key is set to 1.

Each key in the global dictionary is an all-lowercase string, and each key
holds a numerical value. Zero is the default highlight setting for each
option. There are boolean-like options: they hold number 0 or number 1
as their value, and are regarded as an "attribute" that is present or
absent. An example is 'statusline' key: if its value is zero the
colorscheme will not set statusline related highlihgts.

Command-line setting example~
>
	" create a dictionary and set two Briofita options
    let g:briofita_parms = { 'search': 3, 'localcursorline':0 }
<

Allowed Options~

Another dictionary is exported by the colorscheme: >
	    g:briofita_keys.
<
This is an informational dictionary which has all option names as keys. It should
not be changed by the user (the colorscheme would overwrite its contents).

Each key in g:briofita_keys has the same name of a Briofita option.

A simple list of options can be obtained by entering this command: >
	:echo sort(keys(g:briofita_keys))
<

User-set keys in the g:briofita_parms dictionary are acknowledged only if they
belong to g:briofita_keys. That means: if they are allowed.

A more detailed list, with all the highlights assigned to each key, can be
obtained by by issuing this command >
                        :echo g:briofita_keys
<

Menu Entry for Allowed Options~

The briofita-support plugin has a menu entry which makes it a
bit easier to get a list of options and assigned highlights.

All distinct highlights assigned to each key option are reported
per Vim "echomsg" command.

The menu path: >
	--> Plugin (default), or other menu under which you have inserted Briofita
		--> Briofita Colorscheme Support
		    --> Version
			    --> View Briofita informational variable g:briofita_keys
<
This is the third active menu-entry in the "Version" menu-panel.

It performs an ":echomsg g:briofita_keys" command.

Notice that it shows the structure of keys with their connected highlights,
not current settings for each highlight (this you can get via the top-most
active menu entry in the same Version menu panel).


Briofita and Vim options~

Most of the Briofita optional highlights are connected to Vim options/highlights.
If you usually do NOT use some Vim option, you do not need to use the corresponding
Briofita option... except when a highlight you are interested in is part of a
group of highlights named after that option.

CursorLine option cycling~

By use of the companion plugin, briofita-support, it is easy to change
(or "cycle") the CursorLine option: you just need to click on the
corresponding menu entry.  If you do not want to use it, you might create
tool bar buttons for cycling CursorLine, so that each time you click on
them a new option is in effect.

Command-line setting of options~

Enter the below command in Vim command-line. It should change your Search
highlight background:

>
    :let g:briofita_parms['search'] = 2
<
Notice that the effect of this command may not be immediate because the
colorscheme is not aware of command line events. You may need to source it
with the command
>
        :colorscheme briofita.
<

Practical way of setting Briofita options~

This helpfile is a work-in-progress... it currently does not mentions all the
plugin features. Experiment by clicking in different menu entries and by setting
different options until you become well acquainted with Briofita.

Once found your preferred options, click on the "Version" menu, and, under it,
on the menu whose name starts with "Dump". This way a tabpage with all your
current global settings will be created. Edit your .gvimrc file and add the
commands shown in the tabpage into it. This way your favorite options will be
in effect from the time Briofita starts up when you begin a new Vim instance.

Options cycling~

Cycling begins with key value zero, the default for all options.

The colorscheme may alter the value of a dictionary key if it is incorrect, or
if its value is above the limit for the key: then it returns to the initial
value, the default.
                                                                  |briofita-TOC|


==============================================================================

OPTIONS LIST                                       *briofita-options-list*  {{{1

A list of options is provided after this help session.

All the below Briofita options ("parameters") can be set by the user via
command-line. Some of them may be set by clicking selected briofita-support
GUI menu entries (mainly those with "CYCLE" in the menu entry text).

Some options might be meaningful only if you use the corresponding Vim option.
For example if you do not use Vim option "hlsearch" it does not make sense to
set the Briofita option Search ('search' key).

The colorscheme exports a global variable >
	g:briofita_keys
<
which has all the options and the connected highlights in a list.

You may view the variable by issuing a simple Vim ":echo" command.

Or you may use the plugin, by clicking on this menu path: >
	--> Plugin (default), or other menu under which you have inserted Briofita
	--> "Briofita Colorscheme Support" main menu
		--> "Version" sub-menu
		     --> "View Briofita informational variable..." entry
<

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
Brackets~

Dictionary:         g:briofita_parms['brackets']

The 'brackets' boolean key relates to syntax elements currently
created only by the Rainbow plugin (or its siblings) for
parentheses colorization.

Briofita implements this key for improved visualization of lines
which have parts of the text inside parentheses.

State: ON by default.

There is no issue if you let it be ON and you do not have the
Rainbow plugin installed. You may safely ignore this dictionary key.

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
Conceal~

Dictionary:         g:briofita_parms['conceal']

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
ColorColumn~

Dictionary:         g:briofita_parms['colorcolumn']

Command-line example: >
                :let g:briofita_parms['colorcolumn'] = 2
Explore the plugin menu for useful entries connected with this option.
For testing, set Vim option textwidth to a low number so that you do not have
to scroll to the right of the screen to see the cycling effects.

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
CursorLine~

Dictionary:    g:briofita_parms['cursorline']
Variable:      t:briofita_cursorline

Command-line example:
>
    let g:briofita_parms['cursorline'] = 1
<
Linked Option:
	Briofita CursorLine and CursorColumn options are coupled. Changing the
	CursorLine option also affects the CursorColumn highlight: but you will
	see it on your text only if you have enabled the corresponding Vim
	cursorcolumn option. (There is NO corresponding key name "cursorcolumn".)

Applying CursorLine to all tabpages:
	If you want the SAME CursorLine style in all your tab pages, use the
	dictionary as follows and do not set or change the above mentioned "t:"
	variable:
>
			let g:briofita_parms['localcursorline'] = 0
			let g:briofita_parms['cursorline'] = 2
<
Applying CursorLine to the current tabpage:
	If you want DIFFERENT background colors of CursorLine for each tabpage,
	then issue the two commands in the below example FOR THE TAB PAGE WHERE
	YOU ARE:
>
			let g:briofita_parms['localcursorline'] = 1
			set t:briofita_cursorline=3
<
	The example assumes your favorite CursorLine option for the current tab
	is the option with number 3.
	Repeat the SECOND command above for each tabpage where you want a different
	CursorLine background color (change the "3" to a different number in each
	tabpage).

Connected flag:
	Read the topic for the related 'localcursorline' key to know how it may
	affect the behavior of the 'cursorline' key.

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
CursorLineNr~

Dictionary:    g:briofita_parms['cursorlinenr']

Command-line example:
>
    let g:briofita_parms['cursorlinenr'] = 2
<
                                                                  |briofita-TOC|

------------------------------------------------------------------------------
Folded~

Dictionary:      g:briofita_parms['folded']

Command-line setting:
>
    let g:briofita_parms['folded'] = 2
<
This Briofita option is related to the way Vim displays folded items.

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
LocalCursorLine~

Dictionary:   g:briofita_parms['localcursorline']
              ("boolean" option)

Command-line setting:
>
    let g:briofita_parms['localcursorline'] = 1
<
This 'localcursorline' option is the only required entry in the dictionary.
You need to specify it when manually creating a new dictionary. If you use the
companion plugin this is one of the dictionary keys which are automatically
created when you click on selected menu entries.

This option affects the CursorLine Briofita option. It is a flag which may
have 0 or 1 values. When its value is 0, the 'cursorline' parameter applies
to all tabpages. Otherwise, the 'cursorline' parameter applies to the current
tabpage (ie may be different in each one).

(This Briofita option does not directly affect any highlight and does not have
any corresponding Vim option.)

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
Normal~

Dictionary:      g:briofita_parms['normal']

Command-line setting:
>
    let g:briofita_parms['normal'] = 2
<
The Normal highlight is applied to the common text, the text that has no
special syntax.

The last cycle item for the "normal" key has the Normal highlight with
black background, somewhat breaking the colorscheme style. It is an
style exception added to aid in using the colorscheme when the
room has more illumination than usual.

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
Search~

Dictionary:      g:briofita_parms['search']

Command-line setting:
>
    let g:briofita_parms['search'] = 1
<
This Briofita option allows you to change the visual style of the star (`*`) and
search (`/`) commands in Vim normal mode. (You should set the Vim boolean
option hlsearch to see the effect of this Briofita option.)

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
Diff~
Dictionary:     g:briofita_parms['diff']

This key relates to file comparison, when you use the Vim menu >
   --> File
       -->Split Diff with...
<
or when opening diff files (checking patches, for example).

You may cycle, experimenting with the different alternatives, and then define
one of them as your favorite. (Put the corresponding ":let" command in
your .vimrc.)

NOTE: It was difficult for the author to fine tune the options for
the "diff" key, this explains why it currently has so many options.
Perhaps a future version will have fewer options for this key.

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
FoldColumn~

Dictionary:      g:briofita_parms['foldcolumn']

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
MatchParen~

Dictionary:    g:briofita_parms['matchparen']

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
Mix01~

Dictionary:    g:briofita_parms['mix01']

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
Special~

Dictionary:     g:briofita_parms['special']

                                                                  |briofita-TOC|

------------------------------------------------------------------------------
Statusline~

Dictionary:     g:briofita_parms['statusline']

This is one example of the so-called "boolean" options (the
'brackets' key is another one).

The meaning of 'statusline' when its value is zero is: the colorscheme will
not set StatusLine and StatusLineNC. When its value is 1 it means: the
colorscheme will set both highlights.

NOTE:
(1) The statusline you see when the active colorscheme is Briofita may NOT be
    Briofita's statusline: since this is a "boolean" option, it will be
	ignored by the colorscheme unless you set it.

(2) This option is purposefully a "boolean" one, so that you can disable it
    in order not to interfere with any settings originated from your
	statusline plugin.


                                                                  |briofita-TOC|

==============================================================================

TABPAGE LOCAL SETTINGS                           *briofita-local-settings*  {{{1

Local Settings~

Briofita CursorLine option may behave in a way we call "local" via its
tabpage-local settings. Being "local", the CursorLine highlight may
show different color backgrounds for each different tabpage. And this behavior
extends to CursorColumn and other linked/coupled syntax items.

Note: when not "local", such settings are "global", meaning that their items are
displayed equally on all tabpages.

Main Locality Condition~

Do this once for all tabpages:
>
	set the parameter 'localcursorline' to 1 in the global
	("g:") dictionary
<
Complementary Locality Condition~

Do this, creating one different instance per tabpage:
>
	set t:briofita_cursorline = ...
<
where "..." should be a value applicable to the CursorLine option.

If you delete the tabpage variable while the key 'localcursorline' keeps its
value 1:
>
	next time the colorscheme is sourced the tabpage variable will
    be re-created with default value (as 0).
<
The same happens if you set that key to 1 and do not create the tabpage
variable. Even if you delete all the tabpage variables, they will be recreated
with default value on reentry to the tabpage. Except if you reset the
'localcursorline' key (to value 0).

If you intend to manually change the CursorLine option, instead of using
the amenities provided by the plugin menus, remember that: >
	   If the global 'localcursorline' option is reset(0), you should change
	   the global dictionary key g:briofita_parms.cursorline, not the
	   tabpage variable.
< and >
	   If the global 'localcursorline' option is set(1), you should change
	   the t:briofita_cursorline variable, not the dictionary one.
<

If you expected some highlight change which did not happen, try this: >
       click on another tabpage and,
	   then, back to the original one
<
to allow the colorscheme to be re-executed with the new parameter values.
(This applies to users of the tabpagecolorscheme plugin.)



Creating, Setting or Deleting the Tabpage Variable~

You may manually create (or change the value of) the tabpage variable with
the Vim ":let" command. Or you may put the above commands in .vimrc/.gvimrc.

You may delete the tabpage variable with the Vim ":unlet" command.

(There are related "local" menu entries in the briofita-support plugin, which
you may try. Limitation: that part of the plugin was designed with testing in
mind, further development is necessary to fulfill normal user needs.)

When you have the local cursorline feature on, there is no issue if you
set the 'cursorline' parameter in the global dictionary. But remember that
it will not get the same priority as the t:briofita_cursorline variable. The
colorscheme may ignore it, or, even assign into it the value of the
tabpage variable.

Priority of Cursorline Options~

When 'localcursorline' is set (its value is 1), there is an established
priority among the possible Briofita 'cursorline' option sources:

>
	first:  variable  t:briofita_cursorline
	second: dictionary key g:briofita_parms.cursorline
	third:  default setting for cursorline (zero)
<
In the absence of the first, which is the one with the highest priority, the
second is taken. In the absence of the second, the third is used.

Between two existing options, the one having the highest priority is used.

For example:
>
	If you have set both the tabpage variable and the dictionary key,
	the tabpage variable will prevail.

	If you omit both the tabpage variable and the dictionary key,
	the default will be used.
<

A logical consequence of these priorities:
>
    When you manually change the GLOBAL dictionary 'cursorline' key
    and do not perceive any change in display color, verify which setting
    you have in the dictionary for 'localcursorline'. If it is on (if its
    value is 1) the effects will only be visible upon changes of the LOCAL
    tabpage variable. (Or else reset the 'localcursorline' key.)
<

NOTE: the colorscheme may create that tabpage variable if 'localcursorline'
is set and the variable is not defined (its value will be taken either
from the 'cursorline' dictionary key or from the default).



                                                                  |briofita-TOC|

==============================================================================

BRIOFITA SUPPORT PLUGIN                                  *briofita-plugin*  {{{1

The companion plugin, "briofita-support.vim", shows Briofita usage examples
and implements procedures that make it a handy tool for day-to-day use.
Notice that the colorscheme can be used independently of the plugin, but the
plugin will not provide most of its functionality without the colorscheme.



------------------------------------------------------------------------------

BRIOFITA SUPPORT MENUS                                    *briofita-menus*  {{{1

Enter this command >
	    :call g:BriofitaMenu()
<
or put it in your ".gvimrc" in order to insert the Briofita Support menu under
your main "Plugin" menu (by default). Then navigate to the Plugin menu, click on
the Briofita support sub-menu and explore its sub-menu tree.

The clickable menu entries at the top of the main menu, namely >
	Help, About, Basics
	Version
<
An example of menu path for the first line is: >
	--> Plugin (default), or other menu under which you have inserted Briofita
	--> "Briofita Colorscheme Support"
		--> "Help, About, Basics"
<
which will allow you to navigate to the Help (displaying this help file),
the About page, and the sub-menu that has basic actions. The Basics sub-menu
itself has a helpful newbies sub-menu crafted to help new Vim users to set
Briofita-related Vim options.

The Version menu provides release/version and configuration information.

Below these two top menus are entries for cycling Briofita options, which are
presented in this order: >
	colorcolumn
	cursorline
	conceal
	cursorlinenr
	diff
	foldcolumn
	folded
	matchparen
	mix01
	normal
	search
	special
	statusline
<
Just click any entry whose text has an uppercase word "CYCLE" to increase the value of
the corresponding Briofita option. (Currently the plugin does not have a menu entry
for changing the boolean "brackets" key; you may enable or disable it manually,
by using the ":let" command.)

For example, the fifth item in the above list is "diff". The menu path for cycling
it is: >
	--> Plugin (default), or other menu under which you have inserted Briofita
	    --> 'Briofita Colorscheme Support' main menu
	         --> 'CYCLE "diff" Briofita option'
<

For colorcolumn and cursorline there are other menu options under their headings, besides
the basic "CYCLE" one. Your day-to-day operation will likely suffice with the "CYCLE"
button. (Other entries are in fact rarely used.)

Menu Insertion Point (Location)~

The following variable affects the positioning of the menu that is built
by the plugin: >
          g:briofita_root_menu
<
You may set this global variable in your ".vimrc" file. If you specify it,
you should put a dot at the end of its content, otherwise it will be ignored.

An example of alternative location for the menu: suppose you want the
support menu inserted under your "MyPlugins" main menu, for example. Specify
it this way: >
		let g:briofita_root_menu = 'MyPlugins.'
<
(Notice the ending dot "." in the string above.)
The corresponding menu path will be >
		MyPlugins --> Briofita Colorscheme Support.
<
This will allow you to access all branches of the Briofita support menu tree.

Notice that this variable relates only to the menu location, not the menu branch
name. The inserted menu name will always be "Briofita Colorscheme Support".

If the root menu specified in the global variable does not exist, it will
be created.

If the global variable does not exist, the plugin inserts its menu under an
assumed main "Plugin" menu. The resulting menu branch will be as follows: >
		--> Plugin
		    --> Briofita Colorscheme Support
<

If you do not want the plugin menu, uninstall the plugin (delete it from the plugin
directory).

The precise position of the support menu under the root menu (top, middle,
bottom...) is not pre-defined. It will depend on the entries you might already
have under the root menu at the moment in which the menu is inserted.


                                                                  |briofita-TOC|

------------------------------------------------------------------------------

BRIOFITA SUPPORT FUNCTIONS                            *briofita-functions*  {{{1


Some of the global functions available from the plugin are listed below.

g:BriofitaCycleCC()~

A function for cycling Briofita option ColorColumn (dict key: "colorcolumn").

g:BriofitaCycleCL(...)~

Cycling for the Briofita CursorLine parameter (and linked items).

g:BriofitaCycleCLN()~

A function for cycling Briofita option CursorLineNr (dict key: "cursorlinenr").

g:BriofitaCycleConceal()~

A function for cycling Briofita option Conceal (dict key: "conceal").

g:BriofitaCycleCUL(...)~

Example of an alternative implementation for cycling for the Briofita
CursorLine parameter (and linked items).

g:BriofitaCycleDiff()~

A function for cycling Briofita option "diff".

g:BriofitaCycleFolded()~

A function for cycling Briofita option Folded (dict key: "folded").

g:BriofitaCycleFoldColumn()~

A function for cycling Briofita option FoldColumn (dict key: "foldcolumn").

g:BriofitaCycleMix01()~

A function for cycling Briofita option "mix01".

g:BriofitaCycleMP()~

A function for cycling Briofita option MatchParen (dict key: "matchparen").

g:BriofitaCycleNormal()~

A function for cycling Briofita option Normal (dict key: "normal").

g:BriofitaCycleOneKey(dictkey)~

A function for cycling (increasing the value of) one global dictionary key,
a Briofita option/parameter.

g:BriofitaCycleSearch()~

A function for cycling Briofita option Search (dict key: "search").

g:BriofitaLocalCL(...)~

Makes Briofita CursorLine option (and items linked to it) behave locally.

g:BriofitaHighlightsCommander(be_local,cycle_start_point)~

This is an example function that sets a selection of user parameters.

g:BriofitaMenu()~

Builds the briofita-support plugin main menu. The menu has entries for
showing current options, for cycling, etc. By default it is inserted
under a root menu named "Plugin". The user can provide an alternative
root menu in the global variable "g:briofita_root_menu".

g:BriofitaSetOneKey(dictkey,newvalue)~

Example of a function to set a key in the global parameter dictionary.

g:BriofitaSupportMenuString()~

Returns the briofita-support plugin main menu string. It can be called
for menu activation.

g:BriofitaSupportMenuMap(trigger)~

Example of a function that is similar to g:BriofitaSupportMenuString().
But instead of returning the menu string it will execute the mapping
command directly. Its trigger parameter is the shortcut for the map.
(Check its source code and modify it to your needs.)

g:BriofitaToggleStatusline()~

Sets/resets the Briofita "boolean" option 'statusline'.

g:BriofitaVersion()~

Returns a string with version information, and current Briofita options
The below command is an example of how to display it above the command line:
>
		  :echo g:BriofitaVersion().
<
                                                                  |briofita-TOC|


------------------------------------------------------------------------------

BRIOFITA COMMANDS AND MAPS                            *briofita-cmds-maps*  {{{1

This release of the Briofita plugin does not provide commands and maps.
You can easily create them, calling the available global functions.

An EXAMPLE of map creation follows:
>
	     nmap <C-B>     :execute 'popup ' . g:BriofitaSupportMenuString()<cr>
<
The example maps the shortcut keys Control-B to display the plugin menu.
You could put the above mapping command in your .vimrc.

Check the help section "Useful Vim Help entries for newbies" |briofita-vimhelp|
for Vim help entries that tell you how to create maps and commands.

                                                                  |briofita-TOC|


==============================================================================

PERFORMANCE                                         *briofita-performance*  {{{1

General Performance~

This colorscheme has a LOT of syntax groups. I suppose that some users,
depending on their hardware, might detect some slowness while using it.
If this happens to you, let me know. (I have been using it for about two years
with no problem.)

Local CursorLine Performance~

CursorLine has an option, in Briofita, to allow local behavior, ie different
CursorLine backgrounds for each tabpage. This operates seamlessly because
the colorscheme only checks the tabpage variable setting (the t: variable) for
the current tabpage. If the colorscheme had to search all open tabpages it
would lack performance.

If you have written a plugin that sets local CursorLine Briofita option,
your plugin may perform a ":tabdo" and reload the colorscheme for each tabpage,
if necessary.

Briofita's companion plugin, briofita-support, has separate menu entries for
the operations which use ":tabdo".

You may manually activate local settings either by using this plugin's menu or
by calling its global functions. (And via command-line commands, obviously.)

Missing Numerical Options~

NOTE: this applies only if you change the colorscheme source, adding new
options:
If your added option SKIPS a numerical key in the dictionary, and
your user sets an option to a numerical value that is below the maximum
value for the option but matches the absent number, the colorscheme
tries to assign the NEXT entry in the dictionary. This may affect
performance. So, if you change the source, try to keep your dictionary
keys as a sequence of numbers.

                                                                  |briofita-TOC|

==============================================================================

SYNTAX COVERAGE                                        *briofita-coverage*  {{{1

Languages and applications covered by the colorscheme:

Syntaxes with 30 or more highlights each~
>
	Asciidoc, C and C++, Java, Javascript, Markdown,
	Perl, Python, Ruby, Shellscript, Vimscript
<
Syntaxes with 10 to 29 highlights each~
>
	Awk, CSS, HTML/XHTML and XML, Ocaml,
	PL/SQL and SQL, Sed, Tex, Vim Help
<
Here is another list, this one grouping the applications per usage:

Programming languages~
>
    - Java, C/C++
    - Javascript
    - Perl, Python, Ruby
    - Unix Shell scripts
    - SQL, PL/SQL
    - Vimscript language
<
Lightweight markup tools~
>
	- Asciidoc, Fountain, Markdown, Restructured text (rst)
<
Web page editing~
>
	- HTML / XHTML
	- XML
	- CSS
<
Customized highlights for Vim plugins~
>
	BufferSaurus / BufferGator,
	CtrlP, Dirlist,
	Easymotion, Filesearch, IndentGuides, log4j,
	ListMaps, ManpageView,
	NERDTree, Explorer (netrw),
	TabMan, TagList,
	some task/todo plugins,
	some snippets plugins
<

There is highlight support, too, for plugins which edit: >
	desktop files,
	ini files,
	FSTAB entries,
	m4/makefiles
<

                                                                  |briofita-TOC|

------------------------------------------------------------------------------

USEFUL VIM HELP ENTRIES                                 *briofita-vimhelp*  {{{1

Of interest to newbies, below are listed some basic Vim help commands the user
may issue to get information about Vim options that are related to Briofita
options and commands used in connection with the colorscheme customization.

Creating menus or toobar buttons:
             :help creating-menus                            |creating-menus|
             :help gui-toolbar                               |gui-toolbar|

Creating maps or commands:
			 :help map-overview                              |map-overview|
             :help 40.2                                      |40.2|

Basic concepts, commands and options:
             :help 'cursorline                               |'cursorline|
             :help 'cursorcolumn                             |'cursorcolumn|
             :help 'conceallevel                             |'conceallevel|
             :help 'colorcolumn                              |'colorcolumn|
             :help 'number                                   |'number|
	         :help 'hlsearch                                 |'hlsearch|
	         :help :nohlsearch                               |:nohlsearch|
             :help usr_27                                    |usr_27|

==============================================================================

ISSUES                                             *briofita-known-issues*  {{{1

Cleared Highlights~

When more than one highlight definition sources are active (colorschemes and
syntax files, for example) an item may sometimes have its color cleared.

Briofita has an internal guard for preventing cleared Normal highlights. For
added robustness, it tries not to use highlight links.

But it cannot guarantee that cleared highlights will not happen: for more
information about this topic, view the below URL from Stackoverflow:
http://stackoverflow.com/questions/12915797/gvim-remove-syntax-highlighting-groups/16630011#16630011



Vim Help File Editing~

Syntax elements HelpBar / HelpStar, when shown, may be in HIGH CONTRAST.

                                                                  |briofita-TOC|


==============================================================================

HISTORY                                                 *briofita-history*  {{{1


Below are the release notes of Briofita.

------------------------------------------------------------------------------

v3.1.0 (March, 2014)~
    * Colorscheme:
		- Bug fixes.
		- Several changes in options' sequence and alternatives.
		- Dropped previous "no distraction" mode (distractionless option).
		- Improvements highlight styles for C/C++, Perl, Python,
		  Vim Help, Ruby, shellscript, VimL, diff, Asciidoc, PL/SQL,
		  XML, HTML, Java, Manpage
		- Added/changed Syntastic and TagList highlight customizations.
		- Improvements in local options logic and dictionary handling.
    * Plugin:
	    - Added a Snapshot menu entry for easier options display.
	    - Added a parameter dump function and corresponding Dump menu entry.
		  This enables saving user's "favorite" options as executable commands.
	    - Several improvements in the code.
	    - Better text displayed in warnings/errors.
	    - Improved treatment of echoed messages.
		- Better formatting of displayed options; clear separation
		  between global and local options.
		- Enabled refreshing Briofita options without having to restart the plugin.
		- Defined a config variable g:briofita_show_cycle_snapshot for tuning
		  some plugin messages.
		- Changed the name of the global function that shows detailed option
		  information to "g:ShowBriofitaKeysInfo".

v3.0.8 (December, 2013)~
    * Helpfile: added a few topics and corrected some entries.

v3.0.7 (December, 2013)~
    * Colorscheme:
		- Improvements in the function that treats cleared Normal highlight.
		- Added the 'brackets' key to dict as a boolean option.
		- More highlights added to the 'special' key.
		- Added VimLineComment to the 'cursorlinenr' key.
		- Added five more VimL highlights into the 'mix01' key.
		- Added an EasyMotion highlight to the 'search' key.
		- Diff key: changed both style and the order of the options;
		  added DiffComment highlight; one more cycling option added.
		- Changed style of StatusLine highlight under 'statusline' key.
		- ColorColumn key: added highlights for Asciidoc, Html, NERDTree
		  and Markdown, and changed style of XmlCommentPart.
		- Changed or added highlight styles for: Asciidoc, Buffergator, Dirlist,
		  C/C++, Desktop files, FSTAB editing, Ruby, Vim Help, Html, Markdown,
		  NERDTree, netrw (Explorer), Python, Restructured text (rst),
		  Todo/Task plugins, Shellscript, Diff, VimL, CtrlP, ini-files,
		  EasyMotion, Filesearch, Tabman, Make / M4
    * Plugin:
	    - Moved the version submenu to a higher level in the menu tree,
	      keeping help/about/basics submenus grouped in another branch.

v3.0.6 (October, 2013)~
	- Colorscheme: Bug fix: corrected missing entry (in an internal list).
	  Few changes for Asciidoc and Python syntaxes.
	- Helpfile: Added a topic about cleared highlights (under Issues).

v3.0.5 (October, 2013)~
	- Plugin: Added global function g:ShowBriofitaInfo which performs
	  an echo that shows the distinct available highlights for each option,
	  based on variable g:briofita_keys. Added a menu entry for
	  the user to call the new function.
    - Colorscheme: Added global variable g:briofita_keys for exporting the
      available highlights for each option.  Improved highlights
	  for elements like Help, diffFile, Asciidoc, Search, XML, HTML,
	  Awk, C, CSS, Ruby, Javascript, Markdown, NERD Tree, Perl, PL/SQL,
	  SQL, Python, Sed, VimL. Changed some cycling structure options.

v3.0.4 (October, 2013)~
	- Plugin: Improved menu location logic and handling of menu location
	  variables. New menu entry added for cycling the "special" key.
    - Colorscheme: Added highlights to the "special" key (Vim help, manpages,
	  Python). Relocated LineNr cycling to another key. Improved logic for
	  cleared normal highlight. Added special FoldColumn highlight for Normal
	  black background. Improved several highlights, including some related
	  to Vim Diff, Vim Help, Asciidoc, CSS, HTML, Java, Sed, manpage,
	  Markdown, Perl, PL/SQL and Python.

v3.0.3 (August, 2013)~
	- Added one more option to the Folded and Normal highlights.
      The new Normal option has a black background (it provides
      more contrast for use under intense lighting conditions).
    - Improved one of the Asciidoc highlights.
	- Bug fix: boolean options (like statusline) were not previously being
	  cycled.

v3.0.2 (July, 2013)~
	- Improved one highlight in the colorscheme (for HTML).
	- Improved the plugin function that displays the main menu.
	- Bug fix in the plugin function that performs cursorline cycling.

v3.0.1 (July, 2013)~
	- Deleted a few debug commands/comments that had remained in the plugin.
	- Increased the release number/date.

v3.0.0 (July, 2013)~
	- Extensive code refactoring and testing (colorscheme plus companion
	  plugin). This version breaks compatibility with previous version.
	- Some highlights improved, some added. New customization options.
	- The helpfile refers to Vim help instructions on how to create commands
	  or maps, since the plugin is still menu-based. More entries were added
	  to the plugin's GUI menu, including a few basic ones for newbies.
	- Bug fixes.

v2.0.3 (May, 2013)~
	- Reduced contrasting background in a few highlights of these syntaxes:
	  Sql,PL/SQL,Fountain,Vim Language.
	- Increased contrasting background of the IncSearch highlight.
	- Corrections and improvements in the help text.

v2.0.2 (May, 2013)~
    - Changed the default for Search highlight. Cleaned plugin and help files.

v2.0.1 (May, 2013)~
    - Code cleaning. Bug fix: corrected some leftovers from previous
	  development.

v2.0.0 (May, 2013)~
    - Increased major number due to the change in global parameter names. They
	  are not compatible with the previous version.
	- If you have upgraded from a previous version of the colorscheme,
	  please REVIEW your parameters.
	- Added a help file in the the "doc" sub-directory. Most of the text
	  previously in the Vim online page has been moved into the help file.
	- Added a "plugin" file as an example of use of the colorscheme by a
	  script. Please keep in mind that this "plugin" is just an example (at
	  least in this release).
	- Improved highlights for the syntaxes I more frequently use.
	- Previously there were just one huge internal highlights dictionary,
	  this has now been split into small dictionaries for easier change.
	- Suavization of style (less red, less high contrast).
	- Bug fixes and functions improvements.
	- Added option for alternative folding highlights.
    - Most user options are now implemented via global dictionary, keys being
	  lowercase names. The tabpage local option for for cursorline" still
	  uses the same "t:" variable as before.
	- Added an "statusline" option, which may have 0 or 1 values.
	  Highlights for StatusLine will be effective only if the value of this
	  option is 1. Use the value 0 if you want not to affect the highlight set
	  by your preferred Status Line plugin.

v1.5.0 (August, 2012)~
	- Improved color highlights of a few elements.
	- Added an informative function, g:BriofitaVersion. A string with the
	  colorscheme version number is shown if you issue a command like this:
	  ":echo g:BriofitaVersion()". If Briofita is the current color, some
	  parameter information is shown, too.
	- Added a parameter variable for distractionless editing mode.
	- ColorColumn option now accepts 3, meaning 'do not set usual ColorColumn
	  highlight' for that mode.
	- All options defaults are now zero.
	- Parameter variables are reset to default value if outside the proper
	  range.

v1.1 to v.1.4 (July, 2012)~
	- Bug fix on option for CursorLineNr.
	- Improved defaults logic.
	- Improved option *choice_for_colorcolumn.
	- Bug fix on option *choice_for_cursorline.

v1.0~
    FIRST RELEASE NOTES (July, 2012)~
    - Designed only for Vim GUI (gvim); terminals are not supported.
    - Intended for use in Vim versions from v7.3 on.
    - Tested with gVim 7.3 under Precise Pangolin Ubuntu Linux.
    - Background in a shaded dark green color.
    - It displays most of the text in nuances of green, blue, purple or violet,
      although the style is not uniform among different syntaxes.
    - For better contrast it uses red or reverse highlight in a few syntactic
      items of each filetype; in Python indentation errors, for example.
    - It sets a red ICursor via Vim 'guicursor' option.
    - A few highlights can be changed by the user via global options.

                                                                  |briofita-TOC|


==============================================================================

TODO                                                       *briofita-todo*  {{{1

	- Enable an easy "adaptation" of the colorscheme to lighting conditions,
	  via some parameter or option. This need was perceived recently, when I
	  had to attend a course in a sunlit room; crowded as it was, I could not
	  move from my desk near the window, so I had to use some other, brighter
	  colorscheme.

NOTES                                                        *briofita-notes*

Briofita used to have an experimental distraction-less mode.

It has now been dropped. In case you need something in that style we
recommend you search the Vim online site and github for specialized
plugins. Your search may use terms like
>
	dark room, or
	distraction
<
for example. Two such links from the Vim site are provided below: >
	DistractFree plugin:
	http://www.vim.org/scripts/script.php?script_id=4357
< and >
	Goyo plugin:
	http://www.vim.org/scripts/script.php?script_id=4785
<
You may find many more if you search...
                                                                  |briofita-TOC|


==============================================================================
Modeline: {{{1
vim:ts=4:tw=78:ft=help:norl:fdm=marker:
