format.txt  Convert current file to colored HTML, BBCode or whatever
==============================================================================
CONTENTS                                                   format-contents
    1. Intro                                      format-intro
    2. Functionality provided                     format-functionality
        2.1. Commands                             format-commands
        2.2. Functions                            format-functions
    3. Options                                    format-options
    4. Format specification description           format-spec
        4.1. Dictionary keys                      format-spec-keys
        4.2. String descriptions                  format-spec-description
    5. List of built-in format specifications     format-formats
==============================================================================
1. Intro                                                      format-intro
This plugin provides the ability to convert current file to colored HTML, 
BBcode, (in future) LaTeX or whatever you have written specification for.
Features:
    ∙ Flexible format specifications
    ∙ Ability to create abstract stylesheets
    ∙ 'list' and 'listchars' options support (only tab, trail and eol for now)
    ∙ Diffed buffers support (if file is in diff mode and current line is 
      different from other's file line then foreground color is taken from 
      current syntaxID and background color is taken from diff syntax ID)
    ∙ Support for creating numbered lines
    ∙ Folds support
Plugin requires chk, comp, stuf and load plugins.
==============================================================================
2. Functionality provided                             format-functionality
This plugin provides one command and three functions. One function is accessed 
via dictionary returned by load-func-getfunctions function.
------------------------------------------------------------------------------
2.1. Commands                                              format-commands
                                                            format-actions
:FormatCommand {action} ...               format-:Command :FormatCommand
            The only command provided by this plugin. If variable 
            g:formatOptions exists and has key _cprefix, then prefix Format is 
            altered. See load-opt-_cprefix.
                                                      format-action-format
:{range}FormatCommand format [{formatName} [{option1} {value1}]]
            Create a new buffer which contains lines formatted using the 
            specification named {formatName} ("html" by default). If {range} 
            is not given, format the whole file. For list of built-in formats 
            see format-formats. Possible options:
            Option         Value and description
            columns        Unsigned integer greater then zero or -1. Used to 
                           specify number of columns (screen width). Overrides 
                           format-spec-key-columns.
            collapsfiller  Unsigned integer. Overrides 
                           format-option-CollapsFiller.
            foldcolumn     Unsigned integer or -1. Overrides 
                           format-option-FoldColumn.
            allfolds       Bool. Overrides format-option-AllFolds.
            ignorefolds    Bool. Overrides format-option-IgnoreFolds.
            ignorelist     Bool. Overrides format-option-IgnoreList.
            nonr           Bool. Overrides format-option-NoLineNR.
            rnr            Bool. Overrides format-option-RelativeNumber.
            progress       0, 1 or 2. Overrides format-option-ShowProgress.
            formatconcealed  0, 1 or 2. Overrides 
                           format-option-FormatConcealed.
                                                  format-action-diffformat
:{range}FormatCommand diffformat [{formatName} [{option1} {value1}]]
            Like format-action-format, but create a side-by-side diff file. 
            In side-by-side diff format-option-CollapsFiller and 
            format-option-AllFolds are ignored and set to false, you also 
            cannot specify this options on the command line. If in one of the 
            diffed windows 'foldmethod' is not equal to "diff" then 
            format-option-IgnoreFolds is also overriden and set to true.
            Note that in side-by-side diff document in first column is the 
            document where the command were called from.
            Note that if there is only one or no windows where 'diff' is set 
            then empty buffer will be created and nothing will be generated.
:FormatCommand delete [{formatName}]                  format-action-delete
            Delete format specification named {formatName}.
:FormatCommand list                                     format-action-list
            Print a list of format specifications.
:FormatCommand purgecolorcaches             format-action-purgecolorcaches
            Purge color caches. Useful if you change the value of 'background' 
            option since changing colorschemes triggers ColorScheme event 
            which also causes purging color caches. You may also want to do 
            this if you do not want to have styles from previously formatted 
            documents. Useless if format-opt-KeepColorCache is false.
------------------------------------------------------------------------------
2.2. Functions                                            format-functions
Global functions ("Format" prefix can be altered in g:formatOptions._fprefix 
option, see load-opt-_fprefix):
                                                           format-func-Add
FormatAdd({formatName}{specification})                       FormatAdd()
            Add {specification} to the list of specifications and name it 
            {formatName}. If specification named {formatName} already exists 
            then it throws an exception. For the description of 
            {specification} see format-spec.
                                                       format-func-Delete
FormatDelete({formatName})                                 FormatDelete()
            Delete format specification named {formatName}.
Function accessed via dictionary returned by load-func-getfunctions 
function:
                                                        format-func-format
format({formatName}, [{startline}, [{endline}, [{option1}{value1}, ...]]])
            Return the List of lines formatted using the specification named 
            {formatName}. If {startline} is not given, use the whole file. If 
            {endline} is not given, format from the {startline} to the end of 
            file. For possible {option}s see format-action-format.
==============================================================================
3. Options                                                  format-options
                                         b:formatOptions g:formatOptions
All options are located in b:formatOptions and g:formatOptions dictionaries.
KeepColorCache :: Bool                           format-opt-KeepColorCache
        Keep color cache after formatting is done. True by default.
DefaultFormat :: String                           format-opt-DefaultFormat
        Default format specification's name.
IgnoreFolds :: Bool                                 format-opt-IgnoreFolds
        If IgnoreFolds is true, then act as if there were no text folds. See 
        fold.txt for more information about folding. Note that if format 
        specification does not provide "fold" key then closed folds will be 
        ignored even if IgnoreFolds is set to 0.
AllFolds :: Bool                                       format-opt-AllFolds
        If IgnoreFolds is not true and current format has either foldstart or 
        foldend keys (or both), then collect all possible folds and call 
        foldstart at each fold start and foldend at each foldend. Note that 
        this option will overwrite your 'foldminlines' option, so you will 
        have to restore it manually if you terminate formatting process.
FoldColumn :: -1 | 0 | Natural                       format-opt-FoldColumn
        If FoldColumn is set to -1 (default) and IgnoreFolds is not true, then 
        foldcolumn is added to the resulting format if 'foldcolumn' is greater 
        then zero. Other values override 'foldcolumn' option. Note that this 
        option will overwrite your 'foldminlines' option, so you will have to 
        restore it manually if you terminate formatting process.
IgnoreList :: Bool                                   format-opt-IgnoreList
        If IgnoreList is true, then ignore 'list' and 'listchars' options.
        Now plugin supports only tab, trail and eol 'listchars' 
        specifications.
IgnoreTags :: 0 | 1 | 2                              format-opt-IgnoreTags
        Defines whether tags are ignored, see taglist()
        0: do not ignore any tags. In HTML format it produces the following 
           tags: >
               <a href="#line18-0">...</a>
<          (if tag links to the current buffer) and >
               <a href="{path}#line18-0">...</a>
<          (if tag links to other file). Here {path} is a path to the file 
           with tag definition relative to the current directory (if 
           possible). Note that HTML formatter escapes all `<' and `>' 
           characters, so it is safe to use regular expressions to change the 
           tags.
        1: ignore tags that are not in current file (default)
        2: ignore all tags
AddTagCmdEscapes :: [ Char ]                   format-opt-AddTagCmdEscapes
        String, defines a list of characters that should be escaped if `cmd' 
        key in tag description returned by taglist() is an vim pattern. 
        Default: '[]*.~'.
MaxDupTags :: UInt                                   format-opt-MaxDupTags
        Defines a maximum number of tag entries with one name. If actual 
        number of tag entries that share the same name exceeds this value, 
        then this tag is ignored. You can set this option to 0 in order to 
        prevent filtering. Default: 5.
RelativeNumber :: -1 | Bool                      format-opt-RelativeNumber
        If it is true, then it adds relative line numbers, just like when 
        'relativenumber' is set ('relativenumber' was introduced in vim 7.3, 
        but this option will also work in vim 7.2). -1 (default) means that 
        this option will be enabled if 'relativenumber' option is set. 
        Overrides format-opt-NoLineNR.
NoLineNR :: -1 | Bool                                  format-opt-NoLineNR
        If it is true then do not add the line numbers, -1 (default) means 
        "preserve 'number' option" (plugin acts as if NoLineNR were true if 
        'number' is not set and as if it were false otherwise). It does the 
        following:
        1. Sets @_donr@ to 0
        2. Makes "%#" and "%_" return blank strings
        3. Forces skipping applying "linenr" specification
        It has the same effect as removing "linenr" key from specification.
CollapsFiller :: UnsignedInteger                  format-opt-CollapsFiller
        If this value is not zero, number of deleted lines is equal or greater 
        than CollapsFiller and there is "collapsedfiller" key in format 
        specification then this key is used instead of repeating "difffiller" 
        for every deleted line.
IgnoreCursor :: Bool                               format-opt-IgnoreCursor
        If this option is true (default) then cursor position is ignored 
        (cursor line or column do not get highlighted when 'cursorline' or 
        'cursorcolumn' is on, cursor character also is not highlighted).
FormatConcealed :: 0, 1 or 2                    format-opt-FormatConcealed
        If both this option and 'conceallevel' have non-zero values, then only 
        actually shown text will be formatted. Difference between values 1 
        and 2 is that if FormatConcealed value is 1 then 
        format-spec-key-line will be used with specification derived from 
        hl-Concealed higlight group, thus losing information about what 
        characters are actually hidden. And if FormatConcealed value is 2 then 
        format-spec-key-concealed is used, so information about concealed 
        characters can be possibly saved.
ShowProgress :: 0, 1 or 2                          format-opt-ShowProgress
        If this option is not zero then show progress bar. Differencies 
        between 1 and 2:
        Value  Bar
          1    [=>       ] 10% (bar and per cent count)
          2    [=>   ] 1/9 10% (bar, currentline/lastline, per cent count)
               Note that it is currentline/lastline, not 
               linesformatted/linestoformat
        Note that this option alters your 'statusline' and 'laststatus' 
        options during its work, so if you hit <Ctrl-C> you will end with this 
        options altered.
        Note that in terminal it is impossible (at least in version 7.2) to 
        determine actual window size if you resize vim while script is 
        running, so doing that may render progress bar useless. This does not 
        apply to gvim.
DoNotLoad                                             format-opt-DoNotLoad
        If this key exists and plugin is not already loaded, then it will not 
        be loaded (only for g:formatOptions dictionary).
==============================================================================
4. Format specification description                            format-spec
Document is constructed in the following way: >
    ([begin] . "\n")? .
    (
        ([foldend] . "\n")? .
        ([foldstart] . "\n")? .
        [linestart][foldcolumn][linenr]{line}[lineend] . "\n" .
    )* .
    ([end] . "\n")?
where
 [begin] is described by the format-spec-key-begin,
 [end] is described by format-spec-key-end,
 [linestart] by format-spec-key-linestart,
 [foldcolumn] by format-spec-key-foldcolumn,
 [linenr] by format-spec-key-linenr,
 [lineend] by format-spec-key-lineend,
 [foldend] by format-spec-key-foldend,
 [foldstart] by format-spec-key-foldstart,
while {line} may be
 - a sequence of items described by format-spec-key-line (for regular 
   lines),
 - a difffiller described by format-spec-key-difffiller,
 - collapsed sequence of difffillers described by 
   format-spec-key-collapsedfiller,
 - or a folded text described by format-spec-key-fold.
For side-by-side diff generation first all lines of first document are being 
generated, then all lines of second document are being generated (both without 
beginning and ending, format-spec-key-haslf and format-spec-key-nolf are 
ignored) and then generated lines are merged like that: >
    [sbsdstart]{lineOfFirstDocument}[sbsdsep]{lineOfSecondDocument}[sbsdend]
where
 [sbsdstart] is described by the format-spec-key-sbsdstart,
 [sbsdsep] by format-spec-key-sbsdsep,
 [sbsdend] by format-spec-key-sbsdend.
format-spec-key-beginformat-spec-key-endformat-spec-key-haslf and 
format-spec-key-nolf are being processed only after line merge.
Everything is defined in the format specification which is the dictionary with 
the following keys (only `line' key is required):
------------------------------------------------------------------------------
4.1. Dictionary keys                                      format-spec-keys
linestart                                        format-spec-key-linestart
        String, describes each start of line. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         0 for regular lines,
                    1 for folded lines,
                    2 for difffiller,
                    3 for collapsedfiller
        @.@         0 (zero)
        @{stspec}@  Specification derived from "Normal" highlight group or 
                    from both "Normal" and "CursorLine" higlight groups if 
                    'cursorline' is true and format-opt-IgnoreCursor is 
                    false. For folded lines specification changes to "Folded" 
                    highlight group, for difffiller and collapsedfiller lines 
                    specification changes to "DiffDelete" highlight group.
foldcolumn                                      format-spec-key-foldcolumn
        String, describes foldcolumn at the start of each line. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         String that is supposed to be displayed in the real 
                    foldcolumn
        @.@         Folding level
        @{stspec}@  Specification derived from "FoldColumn" highlight group
linenr                                              format-spec-key-linenr
        String, describes line number at the start of each line without folds. 
        Arguments (see format-spec-description) (listed only arguments with 
        non-standart values):
        Argument    Value
        @@@         Same as @-@ for normal lines or an empty string for 
                    difffillers and collapsedfillers
        @.@         0 (zero)
        @{stspec}@  Specification derived from "LineNr" highlight group, from 
                    both "Normal" and "CursorLine" highlight groups if 
                    'cursorline' is true and format-opt-IgnoreCursor is 
                    false or from "Folded" highlight group for folded text
line                                                  format-spec-key-line
        String, describes each differently highlighted group of characters. 
        Arguments take only standart values (see format-spec-description). 
        Note that this the only required key.
lineend                                            format-spec-key-lineend
        String, describes each line end. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         0 for regular lines,
                    1 for folded lines
                    2 for difffiller,
                    3 for collapsedfiller
        @{stspec}@  Specification derived from "Normal" highlight group or 
                    from both "Normal" and "CursorLine" higlight groups if 
                    'cursorline' is true and format-opt-IgnoreCursor is 
                    false. For folded lines specification changes to "Folded" 
                    highlight group, for difffiller and collapsedfiller lines 
                    specification changes to "DiffDelete" highlight group.
tagstart                                          format-spec-key-tagstart
        String, describes the start of each tag. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Tag name.
        @{stspec}@  Undefined (it may be anything)
tagend                                              format-spec-key-tagend
        String, describes the end of each tag. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Tag name.
        @{stspec}@  Undefined (it may be anything)
concealed                                        format-spec-key-concealed
        String, describes the concealed character. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Text actually shown
        @?@         Concealed text (this argument is unique for concealed key)
        @&{stspec}@ Specification derived from actual highlight group (this 
                    argument is unique for concealed key)
        @{stspec}@  Specification derived from "Concealed" highlight group
fold                                                  format-spec-key-fold
        String, describes each fold. Arguments (see format-spec-description
        (listed only arguments with non-standart values):
        Argument    Value
        @@@         Value returned by foldtextresult()
        @.@         0 (zero)
        @{stspec}@  Specification derived from "Folded" highlight group
foldstart                                        format-spec-key-foldstart
        String, describes start of each possible fold. Used only if 
        format-opt-AllFolds is true. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Value returned by foldtextresult()
        @.@         Fold level
        @{stspec}@  Specification derived from "Folded" highlight group
foldend                                            format-spec-key-foldend
        String, describes end of each possible fold. Used only if 
        format-opt-AllFolds is true. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Value returned by foldtextresult()
        @.@         Fold level
        @{stspec}@  Specification derived from "Folded" highlight group
difffiller                                      format-spec-key-difffiller
        String, describes difffiller. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         @_difffillchar@
        @.@         (Total number of filler lines)-(Number of filler lines 
                                                    already created)
        @{stspec}@  Specification derived from "DiffDelete" highlight group
collapsedfiller                            format-spec-key-collapsedfiller
        String, describes collapsed filler. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Number of deleted lines
        @.@         0 (zero)
        @{stspec}@  Specification derived from "DiffDelete" highlight group
begin                                                format-spec-key-begin
        String, describes the beginning of the document. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Empty string
        @.@         0 (zero)
        @-@         0 (zero)
        @{stspec}@  Specification derived from "Normal" highlight group
end                                                    format-spec-key-end
        String, describes the end of the document. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Empty string
        @.@         0 (zero)
        @-@         Number of last formatted line
        @{stspec}@  Specification derived from "Normal" highlight group
sbsdstart                                        format-spec-key-sbsdstart
        String, describes the start of side-by-side diff line. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Empty string
        @.@         0 (zero)
        @-@         Index of the current line (Note that index is not current 
                    line number)
        @{stspec}@  Specification derived from "Normal" highlight group
sbsdsep                                            format-spec-key-sbsdsep
        String, describes the document separator of side-by-side diff line. 
        Arguments (see format-spec-description) (listed only arguments with 
        non-standart values):
        Argument    Value
        @@@         Empty string
        @.@         Number of document on the right site of the separator
        @-@         Index of the current line (Note that index is not current 
                    line number)
        @{stspec}@  Specification derived from "Normal" highlight group
sbsdend                                            format-spec-key-sbsdend
        String, describes the end of side-by-side diff line. Arguments (see 
        format-spec-description) (listed only arguments with non-standart 
        values):
        Argument    Value
        @@@         Empty string
        @.@         Number of documents formatted
        @-@         Index of the current line (Note that index is not current 
                    line number)
        @{stspec}@  Specification derived from "Normal" highlight group
style                                                format-spec-key-style
        String, describes the style of the given highlight group, this style 
        is appended to @:@. Used only once for each highlight group. Arguments 
        (see format-spec-description) (listed only arguments with 
        non-standart values):
        Argument    Value
        @@@         Style id
        @.@         0 (zero)
        @-@         0 (zero)
        @{stspec}@  Specification derived from current style
difffillchar                                  format-spec-key-difffillchar
        String, specifies the character(s) for "%-" and "%~" formats. Can be 
        accessed inside %=...=% via @_difffillchar@. Default: "-".
leadingspace                                  format-spec-key-leadingspace
        String, specifies the character(s) for "%#", "%_" and "% " formats. 
        Can be accessed inside %=...=% via @_leadingspace@. Default: " ".
columns                                            format-spec-key-columns
        Number of columns. If it is not specified, winwidth(0) is used instead 
        (this is the width of the current window, see winwidth()). You can 
        also use special value `-1': in this case length of the longest line 
        will be used.
strlen                                              format-spec-key-strlen
        Function reference, specifies the function that counts length of line 
        for "%_" and "%-" formats and "@=@" argument. Can be accessed inside
        %=...=% via @_strlen@. Default: >
            len(split(string, '\zs'))
nolf                                                  format-spec-key-nolf
        Bool. Normally, new item in list returned by format-func-format 
        starts after each lineend, difffiller, collapsedfiller, fold, 
        foldstart and foldend, but if this option is present and not zero then 
        all items are joined and the list of one item is returned. Makes the 
        script halt for some time at 100% progress (~30s on 1 MiB file), so be 
        patient. Default: 0.
haslf                                                    format-spec-haslf
        Bool. Causes script to additionaly split each item in list returned by 
        format-func-format on "\n" character. It is the only way to include 
        line breaks inside format items. This option is applied after nolf, so 
        set both nolf and haslf to 1 if you want to have line breaks defined 
        only by your format specification. Default: 0.
Note that after each lineend, foldstart and foldend a newline will be added 
unless nolf option is present: using "{range}FormatCommand format 
{formatName}" is equivalent to: >
    let Format=LoadFuncdict().getfunctions("format").format
    let lines=call(Format, [{formatName}, {rangeStart}, {rangeEnd}], {})
    new ++enc=utf-8
    call setline(1, lines)
------------------------------------------------------------------------------
4.2. String descriptions                           format-spec-description
Most specification keys use the following format to describe what plugin 
should actually have in the returned value. It uses %C to describe some common 
strings and format-spec-expression to describe more complex structures. Here 
are the characters that are used in the %C expression. All characters not 
listed here get escaped. Note that you must escape all "@" characters not 
inside the format-spec-expression.
%f, %b                                     format-spec-%f format-spec-%b
        Foreground and background colors (string with format "#RRGGBB"), same 
        as @fgcolor@ and @bgcolor@ inside %=...=%.
%S                                                          format-spec-%S
        Style id ("N" or "N_N" for characters affected by diff mode), same as 
        %=@styleid@=%.
%N                                                          format-spec-%N
        Current line number, same as %=@-@=%.
%C                                                          format-spec-%C
        Column number of the end of string, same as %=@.@=%.
%s                                                          format-spec-%s
        String being formatted, same as %=@@@=%.
%:                                                          format-spec-%:
        All styles in format-spec-key-begin and format-spec-key-end
        current style only in other specification keys, same as 
        %=@:@=%.
%#                                                          format-spec-%#
        Either line number padded to the right with @_leadingspace@ (for 
        normal lines) or a sequence of @_leadingspace@s (for difffiller and 
        collapsedfiller lines) if @_donr@ is true or an empty string 
        otherwise.
%_                                                          format-spec-%_
        @_leadingspace@ repeated @_linenumlen@ times if @_donr@ is true or an 
        empty string otherwise.
%<SPACE>                                               format-spec-%SPACE
        A single @_leadingspace@. Just the same as %=@_leadingspace@=%, but 
        computed only once.
%+                                                          format-spec-%+
        @_leadingspace@ repeated enough times for the line length to be less 
        or equal to @_columns@ (`less' case can appear only if length of 
        @_leadingspace@, computed by format-spec-key-strlen, is greater 
        then 1).
%^                                                          format-spec-%^
        A single @_leadingspace@ if @_donr@ is true or an empty string 
        otherwise. Just the same as %=((@_donr@)?(@_leadingspace@):(''))=%, 
        but computed only once.
%-                                                          format-spec-%-
        @_difffillchar@ repeated enough times for the line length to be less 
        or equal to @_columns@ (`less' case can appear only if length of 
        @_difffillchar@, computed by format-spec-key-strlen, is greater 
        then 1).
%~                                                          format-spec-%~
        A single @_difffillchar@. Just the same as %=@_difffillchar@=%, but 
        computed only once.
------------------------------------------------------------------------------
4.2.1. Expressions in string description                    format-spec-%=
                                           format-spec-%' format-spec-%>
                                                    format-spec-expression
Inside string descriptions can be used complex expressions: 
"%={expression}=%", "%'{expression}'%" and "%>{expression}". In the first form 
all '%' and '\' characters need to be escaped, in the second form you must not 
allow the string "'%" to appear inside expression, and the third form just 
grabs the whole string after "%>".
                                                            format-spec-%!
There is also a special form of expression, valid only at the start of the 
string: "%!{commands}!%", where {commands} is a newline-separated list of 
commands. It can be used to declare variables. Note that you must omit having 
"!%" inside {commands} string.
Inside the expressions you can use the following sequences (use them in place 
of ordinary variables):
@@@                                                        format-spec-@@@
        String being formatted.
@-@                                                        format-spec-@-@
        Current line number.
@.@                                                        format-spec-@.@
        Column number of the end of the string.
@:@                                                        format-spec-@:@
        String with all styles in format-spec-key-begin and 
        format-spec-key-end, string with current style in other 
        specification keys.
@=@                                                        format-spec-@=@
        Length of the string of the current line before expression. Before 
        using this ensure that there are no "'." sequences before it inside 
        character expression.
@{stspec}@                                               format-spec-@key@
        Value of the style specification. Possible {stspec}s:
        {stspec}   Value
        styleid    ID of the current highlight group. For normal lines it is 
                   a single number, for lines with differencies it is equal to 
                   {highID}_{diffhighID}.
        fgcolor    Foreground color transformed to "#RRGGBB" notation.
        bgcolor    Background color transformed to "#RRGGBB" notation.
        bold       Bold syntax attribute.
        italic     Italic syntax attribute.
        inverse    Inverse syntax attribute.
        underline  Underline syntax attribute.
@_{option}@                                             format-spec-@_opt@
        Value of the specified option. Possible {option}s:
        {option}      Value
        leadingspace  Value of the "leadingspace" key from format 
                      specification if it is present, " " otherwise.
        difffillchar  Value of the "difffillchar" key from format 
                      specification if it is present, "-" otherwise.
        columns       Actual number of columns that will be used for the 
                      formats like `%-'.
        fgcolor       Foreground color of "Normal" highlight group. If this 
                      color is an empty string then it is either "#000000" or 
                      "#ffffff" depending on 'background' option.
        bgcolor       Background color of "Normal" highlight group. If this 
                      color is an empty string then it is either "#000000" or 
                      "#ffffff" depending on 'background' option.
        linenumlen    Length of the number of the last line.
        ignorefolds   1 if folds are ignored, 0 otherwise.
        donr          1 if lines will be numbered normally, 0 otherwise.
        dornr         1 if lines will be numbered relatively, 0 otherwise.
        allfolds      1 if AllFolds is on, 0 otherwise
        foldcolumn    0 if foldcolumn is not formatted, width of foldcolumn  
                      in characters otherwise
        ignorecursor  0 if IgnoreCursor is off and either 'cursorcolumn' is 
                      set or cursor is within formatted line range, 1 otherwise
        sbsd          0 if side-by-side diff is not being generated, 1 if 
                      begin, end and sbsd* format specification keys are being 
                      processed, 1+N, where N>0 if N'th document is being 
                      generated
        formatconcealed  0 if concealed text is ignored, 1 or 2 otherwise, see 
                      format-opt-FormatConcealed.
        tags          Dictionary where keys are tag names and values are lists 
                      of pairs [{tag-location}{tag-options}] where each tag 
                      location is either a line number (if tag is located in 
                      the current file) or a pair [{filename}{line-number}]. 
                      Is empty if tags are ignored. See taglist() for 
                      description of {tag-options}.
The following arguments are unique for the format-spec-key-concealed:
@?@                                                        format-spec-@?@
        Concealed text (text that is actually present in the file). Empty 
        string if text is not concealed.
@&{stspec}@                                             format-spec-@&key@
        Value of the actual style specification. For a list of possible 
        {stspec}s see format-spec-@key@. It is an alias for 
        format-spec-@key@ unless used inside format-spec-key-concealed.
@&@                                                        format-spec-@&@
        String with style computed for actual style specification. It is an 
        alias for format-spec-@:@ unless used inside 
        format-spec-key-concealed.
Note that these expressions are replaced in arbitrary order, so you need to 
avoid such ambigious constructions as @_columns@-@=@. Use spaces or brackets 
instead.
==============================================================================
5. List of built-in format specifications                   format-formats
html                                                    format-format-html
        Specification for html format. Supports numbered lines, currently 
        closed folds, tags, AllFolds option. Uses CSS styles; CSS :hover and 
        JavaScript for AllFolds.
html-vimwiki                                    format-format-html-vimwiki
        Specification for html format that can be pasted to vim.wikia.com 
        without any modifications. Supports numbered lines, currently closed 
        folds. Uses CSS in `style' attribute of <div> and <span> tags.
bbcode-unixforum                            format-format-bbcode-unixforum
        Specification for BBcode used on unixforum.org. Supports numbered 
        lines. Does not support background color, because changing background 
        is not available on this forum.
latex-xcolor                                    format-format-latex-xcolor
        Experimental support for dumping to LaTeX format. Uses xcolor and 
        ttfamily fonts.
vim: ft=help:tw=78