.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Text::VimColor 3pm"
.TH Text::VimColor 3pm "2006-02-19" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::VimColor \- syntax color text in HTML or XML using Vim
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&   use Text::VimColor;
\&   my $syntax = Text::VimColor\->new(
\&      file => $0,
\&      filetype => \*(Aqperl\*(Aq,
\&   );
\&
\&   print $syntax\->html;
\&   print $syntax\->xml;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module tries to markup text files according to their syntax.  It can
be used to produce web pages with pretty-printed colourful source code
samples.  It can produce output in the following formats:
.IP "\s-1HTML\s0" 4
.IX Item "HTML"
Valid \s-1XHTML\s0 1.0, with the exact colouring and style left to a \s-1CSS\s0 stylesheet
.IP "\s-1XML\s0" 4
.IX Item "XML"
Pieces of text are marked with \s-1XML\s0 elements in a simple vocabulary,
which can be converted to other formats, for example, using \s-1XSLT\s0
.IP "Perl array" 4
.IX Item "Perl array"
A simple Perl data structure, so that Perl code can be used to turn it
into whatever is needed
.PP
This module works by running the Vim text editor and getting it to apply its
excellent syntax highlighting (aka 'font\-locking') to an input file, and mark
pieces of text according to whether it thinks they are comments, keywords,
strings, etc.  The Perl code then reads back this markup and converts it
to the desired output format.
.PP
This is an object-oriented module.  To use it, create an object with
the \f(CW\*(C`new\*(C'\fR function (as shown above in the \s-1SYNOPSIS\s0) and then call methods
to get the markup out.
.SH "METHODS"
.IX Header "METHODS"
.IP "new(\fIoptions\fR)" 4
.IX Item "new(options)"
Returns a syntax highlighting object.  Pass it a hash of options.
.Sp
The following options are recognised:
.RS 4
.IP "file" 4
.IX Item "file"
The file to syntax highlight.  Can be either a filename or an open file handle.
.Sp
Note that using a filename might allow Vim to guess the file type from its
name if none is specified explicitly.
.Sp
If the file isn't specified while creating the object, it can be given later
in a call to the \f(CW\*(C`syntax_mark_file\*(C'\fR method (see below), allowing a single
Text::VimColor object to be used with multiple input files.
.IP "string" 4
.IX Item "string"
Use this to pass a string to be used as the input.  This is an alternative
to the \f(CW\*(C`file\*(C'\fR option.  A reference to a string will also work.
.Sp
The \f(CW\*(C`syntax_mark_string\*(C'\fR method (see below) is another way to use a string
as input.
.IP "filetype" 4
.IX Item "filetype"
Specify the type of file Vim should expect, in case Vim's automatic
detection by filename or contents doesn't get it right.  This is
particularly important when providing the file as a string of file
handle, since Vim won't be able to use the file extension to guess
the file type.
.Sp
The filetypes recognised by Vim are short strings like 'perl' or 'lisp'.
They are the names of files in the 'syntax' directory in the Vim
distribution.
.Sp
This option, whether or not it is passed to \f(CW\*(C`new()\*(C'\fR, can be overridden
when calling \f(CW\*(C`syntax_mark_file\*(C'\fR and \f(CW\*(C`syntax_mark_string\*(C'\fR, so you can
use the same object to process multiple files of different types.
.IP "html_full_page" 4
.IX Item "html_full_page"
By default the \f(CW\*(C`html()\*(C'\fR output method returns a fragment of \s-1HTML\s0, not a
full file.  To make useful output this must be wrapped in a \f(CW\*(C`<pre>\*(C'\fR
element and a stylesheet must be included from somewhere.  Setting the
\&\f(CW\*(C`html_full_page\*(C'\fR option will instead make the \f(CW\*(C`html()\*(C'\fR method return a
complete stand-alone \s-1XHTML\s0 file.
.Sp
Note that while this is useful for testing, most of the time you'll want to
put the syntax highlighted source code in a page with some other content,
in which case the default output of the \f(CW\*(C`html()\*(C'\fR method is more appropriate.
.IP "html_inline_stylesheet" 4
.IX Item "html_inline_stylesheet"
Turned on by default, but has no effect unless \f(CW\*(C`html_full_page\*(C'\fR is also
enabled.
.Sp
This causes the \s-1CSS\s0 stylesheet defining the colours to be used
to render the markup to be be included in the \s-1HTML\s0 output, in a
\&\f(CW\*(C`<style>\*(C'\fR element.  Turn it off to instead use a \f(CW\*(C`<link>\*(C'\fR
to reference an external stylesheet (recommended if putting more than one
page on the web).
.IP "html_stylesheet" 4
.IX Item "html_stylesheet"
Ignored unless \f(CW\*(C`html_full_page\*(C'\fR and \f(CW\*(C`html_inline_stylesheet\*(C'\fR are both
enabled.
.Sp
This can be set to a stylesheet to include inline in the \s-1HTML\s0 output (the
actual \s-1CSS\s0, not the filename of it).
.IP "html_stylesheet_file" 4
.IX Item "html_stylesheet_file"
Ignored unless \f(CW\*(C`html_full_page\*(C'\fR and \f(CW\*(C`html_inline_stylesheet\*(C'\fR are both
enabled.
.Sp
This can be the filename of a stylesheet to copy into the \s-1HTML\s0 output,
or a file handle to read one from.  If neither this nor \f(CW\*(C`html_stylesheet\*(C'\fR
are given, the supplied stylesheet \fIlight.css\fR will be used instead.
.IP "html_stylesheet_url" 4
.IX Item "html_stylesheet_url"
Ignored unless \f(CW\*(C`html_full_page\*(C'\fR is enabled and \f(CW\*(C`html_inline_stylesheet\*(C'\fR
is disabled.
.Sp
This can be used to supply the \s-1URL\s0 (relative or absolute) or the stylesheet
to be referenced from the \s-1HTML\s0 \f(CW\*(C`<link>\*(C'\fR element in the header.
If this isn't given it will default to using a \f(CW\*(C`file:\*(C'\fR \s-1URL\s0 to reference
the supplied \fIlight.css\fR stylesheet, which is only really useful for testing.
.IP "xml_root_element" 4
.IX Item "xml_root_element"
By default this is true.  If set to a false value, \s-1XML\s0 output will not be
wrapped in a root element called <syn:syntax>, but will be otherwise the
same.  This could allow \s-1XML\s0 output for several files to be concatenated,
but to make it valid \s-1XML\s0 a root element must be added.  Disabling this
option will also remove the binding of the namespace prefix \f(CW\*(C`syn:\*(C'\fR, so
an \f(CW\*(C`xmlns:syn\*(C'\fR attribute would have to be added elsewhere.
.IP "vim_command" 4
.IX Item "vim_command"
The name of the executable which will be run to invoke Vim.
The default is \f(CW\*(C`vim\*(C'\fR.
.IP "vim_options" 4
.IX Item "vim_options"
A reference to an array of options to pass to Vim.  The default options are:
.Sp
.Vb 1
\&   qw( \-RXZ \-i NONE \-u NONE \-N )
.Ve
.IP "vim_let" 4
.IX Item "vim_let"
A reference to a hash of options to set in Vim before the syntax file
is loaded.  Each of these is set using the \f(CW\*(C`:let\*(C'\fR command to the value
specified.  No escaping is done on the values, they are executed exactly
as specified.
.Sp
Values in this hash override some default options.  Use a value of
\&\f(CW\*(C`undef\*(C'\fR to prevent a default option from being set at all.  The
defaults are as follows:
.Sp
.Vb 4
\&   (
\&      perl_include_pod => 1,     # Recognize POD inside Perl code
\&      \*(Aqb:is_bash\*(Aq => 1,          # Allow Bash syntax in shell scripts
\&   )
.Ve
.Sp
These settings can be modified later with the \f(CW\*(C`vim_let()\*(C'\fR method.
.RE
.RS 4
.RE
.IP "vim_let(\fIname\fR => \fIvalue\fR, ...)" 4
.IX Item "vim_let(name => value, ...)"
Change the options that are set with the Vim \f(CW\*(C`let\*(C'\fR command when Vim
is run.  See \f(CW\*(C`new()\*(C'\fR for details.
.IP "syntax_mark_file(\fIfile\fR, \fIoptions...\fR)" 4
.IX Item "syntax_mark_file(file, options...)"
Mark up the specified file.  Subsequent calls to the output methods will then
return the markup.  It is not necessary to call this if a \f(CW\*(C`file\*(C'\fR or \f(CW\*(C`string\*(C'\fR
option was passed to \f(CW\*(C`new()\*(C'\fR.
.Sp
Returns the object it was called on, so an output method can be called
on it directly:
.Sp
.Vb 3
\&   my $syntax = Text::VimColor\->new(
\&      vim_command => \*(Aq/usr/local/bin/special\-vim\*(Aq,
\&   );
\&
\&   foreach (@files) {
\&      print $syntax\->syntax_mark_file($_)\->html;
\&   }
.Ve
.Sp
You can override the filetype set in \fInew()\fR by passing in a \f(CW\*(C`filetype\*(C'\fR
option, like so:
.Sp
.Vb 1
\&   $syntax\->syntax_mark_file($filename, filetype => \*(Aqperl\*(Aq);
.Ve
.Sp
This option will only affect the syntax colouring for that one call,
not for any subsequent ones on the same object.
.IP "syntax_mark_string(\fIstring\fR, \fIoptions...\fR)" 4
.IX Item "syntax_mark_string(string, options...)"
Does the same as \f(CW\*(C`syntax_mark_file\*(C'\fR (see above) but uses a string as input.
\&\fIstring\fR can also be a reference to a string.
Returns the object it was called on.  Supports the \f(CW\*(C`filetype\*(C'\fR option
just as \f(CW\*(C`syntax_mark_file\*(C'\fR does.
.IP "\fIhtml()\fR" 4
.IX Item "html()"
Return \s-1XHTML\s0 markup based on the Vim syntax colouring of the input file.
.Sp
Unless the \f(CW\*(C`html_full_page\*(C'\fR option is set, this will only return a fragment
of \s-1HTML\s0, which can then be incorporated into a full page.  The fragment
will be valid as either \s-1HTML\s0 and \s-1XHTML\s0.
.Sp
The only markup used for the actual text will be \f(CW\*(C`<span>\*(C'\fR elements
wrapped round appropriate pieces of text.  Each one will have a \f(CW\*(C`class\*(C'\fR
attribute set to a name which can be tied to a foreground and background
color in a stylesheet.  The class names used will have the prefix \f(CW\*(C`syn\*(C'\fR,
for example \f(CW\*(C`synComment\*(C'\fR.  For the full list see the section
\&\s-1HIGHLIGHTING\s0 \s-1TYPES\s0 below.
.IP "\fIxml()\fR" 4
.IX Item "xml()"
Returns markup in a simple \s-1XML\s0 vocabulary.  Unless the \f(CW\*(C`xml_root_element\*(C'\fR
option is turned off (it's on by default) this will produce a complete \s-1XML\s0
document, with all the markup inside a \f(CW\*(C`<syntax>\*(C'\fR element.
.Sp
This \s-1XML\s0 output can be transformed into other formats, either using programs
which read it with an \s-1XML\s0 parser, or using \s-1XSLT\s0.  See the
\&\fItext\-vimcolor\fR\|(1) program for an example of how \s-1XSLT\s0 can be used with
XSL-FO to turn this into \s-1PDF\s0.
.Sp
The markup will consist of mixed content with elements wrapping pieces
of text which Vim recognized as being of a particular type.  The names of
the elements used are the ones listed in the \s-1HIGHLIGHTING\s0 \s-1TYPES\s0 section
below.
.Sp
The \f(CW\*(C`<syntax>\*(C'\fR element will declare the namespace for all the
elements prodeced, which will be \f(CW\*(C`http://ns.laxan.com/text\-vimcolor/1\*(C'\fR.
It will also have an attribute called \f(CW\*(C`filename\*(C'\fR, which will be set to the
value returned by the \f(CW\*(C`input_filename\*(C'\fR method, if that returns something
other than undef.
.Sp
The \s-1XML\s0 namespace is also available as \f(CW$Text::VimColor::NAMESPACE_ID\fR.
.IP "\fImarked()\fR" 4
.IX Item "marked()"
This output function returns the marked-up text in the format which the module
stores it in internally.  The data looks like this:
.Sp
.Vb 2
\&   use Data::Dumper;
\&   print Dumper($syntax\->marked);
\&
\&   $VAR1 = [
\&      [ \*(AqStatement\*(Aq, \*(Aqmy\*(Aq ],
\&      [ \*(Aq\*(Aq, \*(Aq \*(Aq ],
\&      [ \*(AqIdentifier\*(Aq, \*(Aq$syntax\*(Aq ],
\&      [ \*(Aq\*(Aq, \*(Aq = \*(Aq ],
\&       ...
\&   ];
.Ve
.Sp
The \f(CW\*(C`marked()\*(C'\fR method returns a reference to an array.  Each item in the
array is itself a reference to an array of two items: the first is one of
the names listed in the \s-1HIGHLIGHTING\s0 \s-1TYPES\s0 section below (or the empty
string if none apply), and the second is the actual piece of text.
.IP "\fIinput_filename()\fR" 4
.IX Item "input_filename()"
Returns the filename of the input file, or undef if a filename wasn't
specified.
.SH "HIGHLIGHTING TYPES"
.IX Header "HIGHLIGHTING TYPES"
The following list gives the names of highlighting types which will be
set for pieces of text.  For \s-1HTML\s0 output, these will appear as \s-1CSS\s0 class
names, except that they will all have the prefix \f(CW\*(C`syn\*(C'\fR added.  For \s-1XML\s0
output, these will be the names of elements which will all be in the
namespace \f(CW\*(C`http://ns.laxan.com/text\-vimcolor/1\*(C'\fR.
.PP
Here is the complete list:
.IP "\(bu" 4
Comment
.IP "\(bu" 4
Constant
.IP "\(bu" 4
Identifier
.IP "\(bu" 4
Statement
.IP "\(bu" 4
PreProc
.IP "\(bu" 4
Type
.IP "\(bu" 4
Special
.IP "\(bu" 4
Underlined
.IP "\(bu" 4
Error
.IP "\(bu" 4
Todo
.SH "RELATED  MODULES"
.IX Header "RELATED  MODULES"
These modules allow Text::VimColor to be used more easily in particular
environments:
.IP "Apache::VimColor" 4
.IX Item "Apache::VimColor"
.PD 0
.IP "Kwiki::VimMode" 4
.IX Item "Kwiki::VimMode"
.IP "Template-Plugin-VimColor" 4
.IX Item "Template-Plugin-VimColor"
.PD
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "\fItext\-vimcolor\fR\|(1)" 4
.IX Item "text-vimcolor"
A simple command line interface to this module's features.  It can be used
to produce \s-1HTML\s0 and \s-1XML\s0 output, and can also generate \s-1PDF\s0 output using
an \s-1XSLT/XSL\-FO\s0 stylesheet and the \s-1FOP\s0 processor.
.IP "http://www.vim.org/" 4
.IX Item "http://www.vim.org/"
Everything to do with the Vim text editor.
.IP "http://ungwe.org/blog/" 4
.IX Item "http://ungwe.org/blog/"
The author's weblog, which uses this module.  It is used to make the code
samples look pretty.
.SH "BUGS"
.IX Header "BUGS"
Quite a few, actually:
.IP "\(bu" 4
Apparently this module doesn't always work if run from within a 'gvim'
window, although I've been unable to reproduce this so far.
\&\s-1CPAN\s0 bug #11555.
.IP "\(bu" 4
Things can break if there is already a Vim swapfile, but sometimes it
seems to work.
.IP "\(bu" 4
There should be a way of getting a \s-1DOM\s0 object back instead of an \s-1XML\s0 string.
.IP "\(bu" 4
It should be possible to choose between \s-1HTML\s0 and \s-1XHTML\s0, and perhaps there
should be some control over the \s-1DOCTYPE\s0 declaration when a complete file is
produced.
.IP "\(bu" 4
With Vim versions earlier than 6.2 there is a 2 second delay each time
Vim is run.
.IP "\(bu" 4
It doesn't work on Windows.  I am unlikely to fix this, but if anyone
who knows Windows can sort it out let me know.
.SH "AUTHOR"
.IX Header "AUTHOR"
Geoff Richards <qef@laxan.com>
.PP
The Vim script \fImark.vim\fR is a crufted version of \fI2html.vim\fR by
Bram Moolenaar <Bram@vim.org> and
David Ne\ev{c}as (Yeti) <yeti@physics.muni.cz>.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002\-2006, Geoff Richards.
.PP
This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.