format.txt Convert current file to colored HTML, BBCode or whatever
==============================================================================
==============================================================================
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.
==============================================================================
This plugin provides one command and three functions. One function is accessed
------------------------------------------------------------------------------
The only command provided by this plugin. If variable
:{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
Option Value and description
columns Unsigned integer greater then zero or -1. Used to
specify number of columns (screen width). Overrides
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.
:{range}FormatCommand diffformat [{formatName} [{option1} {value1}]]
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.
Delete format specification named {formatName}.
Print a list of format specifications.
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
------------------------------------------------------------------------------
Global functions ("Format" prefix can be altered in g:formatOptions._fprefix
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
Delete format specification named {formatName}.
function:
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
==============================================================================
Keep color cache after formatting is done. True by default.
Default format specification's name.
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.
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.
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.
If IgnoreList is true, then ignore 'list' and 'listchars' options.
Now plugin supports only tab, trail and eol 'listchars'
specifications.
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
String, defines a list of characters that should be escaped if `cmd'
key in tag description returned by taglist() is an vim pattern.
Default: '[]*.~'.
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.
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.
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.
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 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).
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
hl-Concealed higlight group, thus losing information about what
characters are actually hidden. And if FormatConcealed value is 2 then
characters can be possibly saved.
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.
If this key exists and plugin is not already loaded, then it will not
==============================================================================
Document is constructed in the following way: >
([begin] . "\n")? .
(
([foldend] . "\n")? .
([foldstart] . "\n")? .
[linestart][foldcolumn][linenr]{line}[lineend] . "\n" .
)* .
([end] . "\n")?
where
while {line} may be
lines),
- collapsed sequence of difffillers described by
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
ignored) and then generated lines are merged like that: >
[sbsdstart]{lineOfFirstDocument}[sbsdsep]{lineOfSecondDocument}[sbsdend]
where
Everything is defined in the format specification which is the dictionary with
the following keys (only `line' key is required):
------------------------------------------------------------------------------
String, describes each start of line. Arguments (see
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
false. For folded lines specification changes to "Folded"
highlight group, for difffiller and collapsedfiller lines
specification changes to "DiffDelete" highlight group.
String, describes foldcolumn at the start of each line. Arguments (see
values):
Argument Value
@@@ String that is supposed to be displayed in the real
foldcolumn
@.@ Folding level
@{stspec}@ Specification derived from "FoldColumn" highlight group
String, describes line number at the start of each line without folds.
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
false or from "Folded" highlight group for folded text
String, describes each differently highlighted group of characters.
Note that this the only required key.
String, describes each line end. Arguments (see
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
false. For folded lines specification changes to "Folded"
highlight group, for difffiller and collapsedfiller lines
specification changes to "DiffDelete" highlight group.
String, describes the start of each tag. Arguments (see
values):
Argument Value
@@@ Tag name.
@{stspec}@ Undefined (it may be anything)
String, describes the end of each tag. Arguments (see
values):
Argument Value
@@@ Tag name.
@{stspec}@ Undefined (it may be anything)
String, describes the concealed character. Arguments (see
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
(listed only arguments with non-standart values):
Argument Value
@@@ Value returned by foldtextresult()
@.@ 0 (zero)
@{stspec}@ Specification derived from "Folded" highlight group
String, describes start of each possible fold. Used only if
values):
Argument Value
@@@ Value returned by foldtextresult()
@.@ Fold level
@{stspec}@ Specification derived from "Folded" highlight group
String, describes end of each possible fold. Used only if
values):
Argument Value
@@@ Value returned by foldtextresult()
@.@ Fold level
@{stspec}@ Specification derived from "Folded" highlight group
String, describes difffiller. Arguments (see
values):
Argument Value
@@@ @_difffillchar@
@.@ (Total number of filler lines)-(Number of filler lines
already created)
@{stspec}@ Specification derived from "DiffDelete" highlight group
String, describes collapsed filler. Arguments (see
values):
Argument Value
@@@ Number of deleted lines
@.@ 0 (zero)
@{stspec}@ Specification derived from "DiffDelete" highlight group
String, describes the beginning of the document. Arguments (see
values):
Argument Value
@@@ Empty string
@.@ 0 (zero)
@-@ 0 (zero)
@{stspec}@ Specification derived from "Normal" highlight group
String, describes the end of the document. Arguments (see
values):
Argument Value
@@@ Empty string
@.@ 0 (zero)
@-@ Number of last formatted line
@{stspec}@ Specification derived from "Normal" highlight group
String, describes the start of side-by-side diff line. Arguments (see
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
String, describes the document separator of side-by-side diff line.
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
String, describes the end of side-by-side diff line. Arguments (see
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
String, describes the style of the given highlight group, this style
is appended to @:@. Used only once for each highlight group. Arguments
non-standart values):
Argument Value
@@@ Style id
@.@ 0 (zero)
@-@ 0 (zero)
@{stspec}@ Specification derived from current style
String, specifies the character(s) for "%-" and "%~" formats. Can be
accessed inside %=...=% via @_difffillchar@. Default: "-".
String, specifies the character(s) for "%#", "%_" and "% " formats.
Can be accessed inside %=...=% via @_leadingspace@. Default: " ".
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.
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'))
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.
Bool. Causes script to additionaly split each item in list returned by
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 lines=call(Format, [{formatName}, {rangeStart}, {rangeEnd}], {})
new ++enc=utf-8
call setline(1, lines)
------------------------------------------------------------------------------
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
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
Foreground and background colors (string with format "#RRGGBB"), same
as @fgcolor@ and @bgcolor@ inside %=...=%.
Style id ("N" or "N_N" for characters affected by diff mode), same as
%=@styleid@=%.
Current line number, same as %=@-@=%.
Column number of the end of string, same as %=@.@=%.
String being formatted, same as %=@@@=%.
current style only in other specification keys, same as
%=@:@=%.
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.
@_leadingspace@ repeated @_linenumlen@ times if @_donr@ is true or an
empty string otherwise.
A single @_leadingspace@. Just the same as %=@_leadingspace@=%, but
computed only once.
@_leadingspace@ repeated enough times for the line length to be less
or equal to @_columns@ (`less' case can appear only if length of
then 1).
A single @_leadingspace@ if @_donr@ is true or an empty string
otherwise. Just the same as %=((@_donr@)?(@_leadingspace@):(''))=%,
but computed only once.
@_difffillchar@ repeated enough times for the line length to be less
or equal to @_columns@ (`less' case can appear only if length of
then 1).
A single @_difffillchar@. Just the same as %=@_difffillchar@=%, but
computed only once.
------------------------------------------------------------------------------
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 "%>".
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):
String being formatted.
Current line number.
Column number of the end of the string.
specification keys.
Length of the string of the current line before expression. Before
using this ensure that there are no "'." sequences before it inside
character expression.
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.
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
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}.
Concealed text (text that is actually present in the file). Empty
string if text is not concealed.
Value of the actual style specification. For a list of possible
String with style computed for actual style specification. It is an
Note that these expressions are replaced in arbitrary order, so you need to
avoid such ambigious constructions as @_columns@-@=@. Use spaces or brackets
instead.
==============================================================================
Specification for html format. Supports numbered lines, currently
closed folds, tags, AllFolds option. Uses CSS styles; CSS :hover and
JavaScript for AllFolds.
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.
Specification for BBcode used on unixforum.org. Supports numbered
lines. Does not support background color, because changing background
is not available on this forum.
Experimental support for dumping to LaTeX format. Uses xcolor and
ttfamily fonts.
vim: ft=help:tw=78