/tmp/format-help-0/doc/format.txt

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. Features format-features

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 frawor plugin.

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

2. Functionality provided format-functionality

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

2.1. Commands format-commands

format-actions

:Format {action} ... format-:Command :FormatCommand

The only command provided by this plugin.

format-action-format

:{range}Format 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. This

option is used to specify number of columns (screen

width). Overrides format-spec-key-columns.

to Defines file where result should be saved. If no

file was specified, new buffer will be created.

number Bool (`number' or `nonumber').

Overrides format-o-NoLineNR, does the opposite to

it.

relativenumber Bool (`relativenumber' or `norelativenumber').

Overrides format-o-RelativeNumber.

list Bool (`list' or `nolist').

Overrides format-o-IgnoreList.

Does the opposite to IgnoreList option.

starttagreg Regex (in very nomagic mode: /\V).

Overrides format-o-StartTagReg.

endtagreg Regex (in very nomagic mode: /\V).

Overrides format-o-EndTagReg.

tags False (`notags'), `local' or `all'.

Overrides format-o-IgnoreTags.

foldcolumn `nofoldcolumn', unsigned integer or -1.

Overrides format-o-FoldColumn.

folds Bool (`folds' or `nofolds').

Overrides format-o-IgnoreFolds, does the opposite

to it.

signs Bool (`signs' or `nosigns').

Overrides format-o-IgnoreSigns, does the opposite

to it.

concealed False (`noconcealed'), `show' or `both'.

Overrides format-o-FormatConcealed.

progress False (`noprogress'), `lines' or `percent'.

Overrides format-o-ShowProgress.

collapsfiller `nocollapsfiller' or unsigned integer.

Overrides format-o-CollapsFiller.

allfolds Bool (`allfolds' or `noallfolds').

Overrides format-o-AllFolds.

format-action-diffformat

:{range}Format diffformat [{formatName} [{option1} {value1}]]

Like format-action-format, but create a side-by-side diff file.

In side-by-side diff format-o-CollapsFiller and

format-o-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-o-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.

:Format list format-action-list

Print a list of format specifications.

:Format 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-o-KeepColorCache is false.

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

2.2. Features format-features

format.add : function ({formatName}, {specification}) format-f-format.add

+ unload

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.

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

3. Options format-options

b:formatOptions g:formatOptions

All options are located either in b:formatOptions and g:formatOptions

dictionaries or in [gb]:format_{option} variables (see frawor-f-getoption).

KeepColorCache :: Bool format-o-KeepColorCache

Keep color cache after formatting is done. Default: 1.

DefaultFormat :: String format-o-DefaultFormat

Default format specification's name. Default: html.

IgnoreFolds :: Bool format-o-IgnoreFolds

If IgnoreFolds is true, then act as if there were no text folds. See

fold.txt for more information about folding. Default: 0.

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-o-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. Default: 0.

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-o-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-o-IgnoreList

If IgnoreList is true, then ignore 'list' and 'listchars' options.

Now plugin supports only tab, trail and eol 'listchars'

specifications. Default: 0.

IgnoreSigns :: Bool format-o-IgnoreSigns

If IgnoreSigns is true, then placed signs are ignored (see :sign).

Default: 0.

StartTagReg :: Regex format-o-StartTagReg

Defines regular expression that must match before the start of the tag

text. Regex must be in very nomagic mode (/\V) and it is highly

recommended that you use only zero-width atoms here (/zero-width).

EndTagReg :: Regex format-o-EndTagReg

Like format-o-StartTagReg, but defines regex that must be matched

after end of the tag text.

IgnoreTags :: 0 | 1 | 2 format-o-IgnoreTags

Defines whether tags are ignored, see taglist()

0: do not ignore any tags. In HTML format it produces the following

tags: >

< (if tag links to the current buffer) and >

< (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-o-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-o-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-o-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-o-NoLineNR.

NoLineNR :: -1 | Bool format-o-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-o-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. If "difffiller" key is absent, then this

option is ignored and plugin will act as if this option was set to 1.

IgnoreCursor :: Bool format-o-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-o-FormatConcealed

If both this option and 'conceallevel' have non-zero values, then only

actually shown text will be formatted. Difference between values

1 (default) 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-o-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

Default: 0.

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.

ColorFile :: 0 or filename (file must be readable) format-o-ColorFile

If this option is not zero, then read colors from file {ColorFile}

instead of {rtp}/config/formatvim/colors-default-'t_Co'.yaml. Relevant

only for vim running in color terminal or when using

format-format-csi (in the latter case

{rtp}/config/formatvim/colors-default.yaml is used by default which

has only 16 colors). It is allowed to skip {rtp}/config/formatvim

part: if no path separators or forward slashes appear in the option

value then it is searched there.

Format of the file must be the following (it is a very limited subset

of YAML):

# Comment

--- # Document start (may be omitted)

# Default color

- "#000000" # Color 0

- "#abcdef" # Color 1

# Yet another comment

- "#dead00" # Color 2

... # Document end (may be omitted)

# Note the following: each non-comment line must start with `- '

# (a dash and a space, exactly at the start of line) followed by

# an opening quote (either «'» or «"»), a hash, four hexadecimal

# digits and a closing quote («'» or «"» depending on what you

# have chosen before).

< Note that this option must be set before format.vim is loaded. All

changes made to this option will be ignored if plugin is already

loaded (though you may use frawor#Reload()).

In the tools/ directory there is a script which helps you with

creating color table: tools/getcolors.pl. It requires perl bindings to

imagemagick, imagemagick shell commands and xdotool (to get focused

window) installed, latter is optional. Usage is the following: >

# If you have N-colored terminal

./tools/getcolors.pl colors.yaml N

# If you created a screenshot with color table by yourself and

# want getcolors.pl to parse it (lines and columns are arguments

# to SetupTable function in colortable.vim)

./tools/getcolors.pl image.png lines columns > colors.yaml

< Note: you can’t use the script in first form with less then four

colors.

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

4. Format specification description format-spec

Document is constructed in the following way: >

[begin]?

(

[foldend]?

[foldstart]?

[linestart][foldcolumn][sign][clstart][linenr]{line}[clend][lineend]

[end]?

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,

[sign] by format-spec-key-sign,

[clstart] by format-spec-key-clstart,

[linenr] by format-spec-key-linenr,

[clend] by format-spec-key-clend,

[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-begin, format-spec-key-end, format-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

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

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

foldstart format-spec-key-foldstart

String, describes start of each possible fold. Used only if

format-o-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

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. 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

sign format-spec-key-sign

String, describes sign 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

sign column or path to the icon

@.@ 0 if no sign is placed on this line,

1 for text sign,

2 for icon sign

@{stspec}@ Specification derived from "SignColumn" highlight group or

whatever is defined in texthl property of the current sign

(see :sign-define).

clstart format-spec-key-clstart

String, describes start of cursor line. It is used only if

'cursorline' is true and format-o-IgnoreCursor is false. Arguments

(see format-spec-description) (listed only arguments with

non-standart values):

Argument Value

@@@ Empty string.

@.@ 0 (zero)

@{stspec}@ Specification derived from "Normal" and "CursorLine"

highlight groups.

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-o-IgnoreCursor is

false or from "Folded" highlight group for folded text

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)

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.

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

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)

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

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

clend format-spec-key-clend

String, describes end of cursor line. It is used only if 'cursorline'

is true and format-o-IgnoreCursor is false. Arguments (see

format-spec-description) (listed only arguments with non-standart

values):

Argument Value

@@@ Empty string.

@.@ 0 (zero)

@{stspec}@ Specification derived from "Normal" and "CursorLine"

highlight groups.

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. For

folded lines specification changes to "Folded" highlight

group, for difffiller and collapsedfiller lines

specification changes to "DiffDelete" highlight group.

foldend format-spec-key-foldend

String, describes end of each possible fold. Used only if

format-o-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

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

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

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

strescape format-spec-key-strescape

String, specifies expression that should be used to obtain escaped

string for current format. In expression `@@@' should represent

escaped value.

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.

addopts format-spec-addopts

Dictionary. All keys from this dictionary are copied (deepcopy())

and accessible as format-spec-@__key@. Only keys containing latin

letters, digits and underscores are allowed.

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 are reserved and throw an error.

%%, %@ format-spec-%% format-spec-%@

Percent sign and `at' symbol.

%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@=%.

%.S format-spec-%.S

Concealed 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. Escaped using format-spec-key-strescape.

%.s format-spec-%.s

Like format-spec-%s, but for concealed text.

%: 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@=%.

%.- format-spec-%.-

@_foldfillchar@ repeated enough times for the line length to be less

or equal to @_columns@ (`less' case can appear only if length of

@_foldfillchar@, computed by format-spec-key-strlen, is greater

then 1).

%.~ format-spec-%.~

A single @_foldfillchar@. Just the same as %=@_foldfillchar@=%.

%| format-spec-%|

A single @_vertseparator@. Just the same as %=@_vertseparator@=%.

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

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.

@~@ format-spec-@~@

Dictionary with style specification. For a list of its keys, see

format-spec-@key@.

@_{option}@ format-spec-@_opt@

Value of the specified option. Possible {option}s:

{option} Value

leadingspace Space escaped using format-spec-key-strescape

expression.

difffillchar Value of the diff item in 'fillchars' option if it is

present, "-" otherwise. Escaped.

foldfillchar Value of the fold item in 'fillchars' option if it is

present, "-" otherwise. Escaped.

vertseparator Value of the vert item in 'fillchars' option if it is

present, "|" otherwise. Escaped.

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-o-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}.

curtags Dictionary where keys are line numbers and values are

lists of {tag-options} (see taglist()). Only tags from

current file are present in this dictionary.

cline Number of line under the cursor.

docline 0 if 'cursorline' option is false or ignored,

1 otherwise, see format-o-IgnoreCursor

dosigns 0 if signs are not present or ignored, 1 otherwise.

See format-o-IgnoreSigns.

signdefinitions Dictionary where keys are sign names and values are

dictionaries {{sign-description}: {value}} (with

additional key `id' containing sign name), see

:sign-define.

placedsigns Dictionary where keys are line numbers and values are

2-tuples (id, sign-definition).

strescape String equal to format-spec-key-strescape.

@__key@ format-spec-@__key@

Value of the specified key defined in format-spec-addopts (well,

deepcopy() of it).

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.

@^@ format-spec-@^@

Dictionary with actual style specification. For a list of possible

keys, see format-spec-@key@. It is an alias for format-spec-@~@

unless used outside 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.

csi format-format-csi

Uses terminal escape sequences to describe color information.