Provided by: libtext-vimcolor-perl_0.11-2_amd64 bug

NAME

       Text::VimColor - syntax color text in HTML or XML using Vim

SYNOPSIS

          use Text::VimColor;
          my $syntax = Text::VimColor->new(
             file => $0,
             filetype => 'perl',
          );

          print $syntax->html;
          print $syntax->xml;

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:

       HTML
           Valid XHTML 1.0, with the exact colouring and style left to a CSS stylesheet

       XML Pieces of text are marked with XML elements in a simple vocabulary, which can be
           converted to other formats, for example, using XSLT

       Perl array
           A simple Perl data structure, so that Perl code can be used to turn it into whatever
           is needed

       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.

       This is an object-oriented module.  To use it, create an object with the "new" function
       (as shown above in the SYNOPSIS) and then call methods to get the markup out.

METHODS

       new(options)
           Returns a syntax highlighting object.  Pass it a hash of options.

           The following options are recognised:

           file
               The file to syntax highlight.  Can be either a filename or an open file handle.

               Note that using a filename might allow Vim to guess the file type from its name if
               none is specified explicitly.

               If the file isn't specified while creating the object, it can be given later in a
               call to the "syntax_mark_file" method (see below), allowing a single
               Text::VimColor object to be used with multiple input files.

           string
               Use this to pass a string to be used as the input.  This is an alternative to the
               "file" option.  A reference to a string will also work.

               The "syntax_mark_string" method (see below) is another way to use a string as
               input.

           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.

               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.

               This option, whether or not it is passed to "new()", can be overridden when
               calling "syntax_mark_file" and "syntax_mark_string", so you can use the same
               object to process multiple files of different types.

           html_full_page
               By default the "html()" output method returns a fragment of HTML, not a full file.
               To make useful output this must be wrapped in a "<pre>" element and a stylesheet
               must be included from somewhere.  Setting the "html_full_page" option will instead
               make the "html()" method return a complete stand-alone XHTML file.

               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 "html()" method is more appropriate.

           html_inline_stylesheet
               Turned on by default, but has no effect unless "html_full_page" is also enabled.

               This causes the CSS stylesheet defining the colours to be used to render the
               markup to be be included in the HTML output, in a "<style>" element.  Turn it off
               to instead use a "<link>" to reference an external stylesheet (recommended if
               putting more than one page on the web).

           html_stylesheet
               Ignored unless "html_full_page" and "html_inline_stylesheet" are both enabled.

               This can be set to a stylesheet to include inline in the HTML output (the actual
               CSS, not the filename of it).

           html_stylesheet_file
               Ignored unless "html_full_page" and "html_inline_stylesheet" are both enabled.

               This can be the filename of a stylesheet to copy into the HTML output, or a file
               handle to read one from.  If neither this nor "html_stylesheet" are given, the
               supplied stylesheet light.css will be used instead.

           html_stylesheet_url
               Ignored unless "html_full_page" is enabled and "html_inline_stylesheet" is
               disabled.

               This can be used to supply the URL (relative or absolute) or the stylesheet to be
               referenced from the HTML "<link>" element in the header.  If this isn't given it
               will default to using a "file:" URL to reference the supplied light.css
               stylesheet, which is only really useful for testing.

           xml_root_element
               By default this is true.  If set to a false value, XML output will not be wrapped
               in a root element called <syn:syntax>, but will be otherwise the same.  This could
               allow XML output for several files to be concatenated, but to make it valid XML a
               root element must be added.  Disabling this option will also remove the binding of
               the namespace prefix "syn:", so an "xmlns:syn" attribute would have to be added
               elsewhere.

           vim_command
               The name of the executable which will be run to invoke Vim.  The default is "vim".

           vim_options
               A reference to an array of options to pass to Vim.  The default options are:

                  qw( -RXZ -i NONE -u NONE -N )

           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 ":let" command to the value specified.  No escaping
               is done on the values, they are executed exactly as specified.

               Values in this hash override some default options.  Use a value of "undef" to
               prevent a default option from being set at all.  The defaults are as follows:

                  (
                     perl_include_pod => 1,     # Recognize POD inside Perl code
                     'b:is_bash' => 1,          # Allow Bash syntax in shell scripts
                  )

               These settings can be modified later with the "vim_let()" method.

       vim_let(name => value, ...)
           Change the options that are set with the Vim "let" command when Vim is run.  See
           "new()" for details.

       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 "file" or "string" option was
           passed to "new()".

           Returns the object it was called on, so an output method can be called on it directly:

              my $syntax = Text::VimColor->new(
                 vim_command => '/usr/local/bin/special-vim',
              );

              foreach (@files) {
                 print $syntax->syntax_mark_file($_)->html;
              }

           You can override the filetype set in new() by passing in a "filetype" option, like so:

              $syntax->syntax_mark_file($filename, filetype => 'perl');

           This option will only affect the syntax colouring for that one call, not for any
           subsequent ones on the same object.

       syntax_mark_string(string, options...)
           Does the same as "syntax_mark_file" (see above) but uses a string as input.  string
           can also be a reference to a string.  Returns the object it was called on.  Supports
           the "filetype" option just as "syntax_mark_file" does.

       html()
           Return XHTML markup based on the Vim syntax colouring of the input file.

           Unless the "html_full_page" option is set, this will only return a fragment of HTML,
           which can then be incorporated into a full page.  The fragment will be valid as either
           HTML and XHTML.

           The only markup used for the actual text will be "<span>" elements wrapped round
           appropriate pieces of text.  Each one will have a "class" 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 "syn", for example "synComment".  For the full list
           see the section HIGHLIGHTING TYPES below.

       xml()
           Returns markup in a simple XML vocabulary.  Unless the "xml_root_element" option is
           turned off (it's on by default) this will produce a complete XML document, with all
           the markup inside a "<syntax>" element.

           This XML output can be transformed into other formats, either using programs which
           read it with an XML parser, or using XSLT.  See the text-vimcolor(1) program for an
           example of how XSLT can be used with XSL-FO to turn this into PDF.

           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 HIGHLIGHTING TYPES section below.

           The "<syntax>" element will declare the namespace for all the elements prodeced, which
           will be "http://ns.laxan.com/text-vimcolor/1".  It will also have an attribute called
           "filename", which will be set to the value returned by the "input_filename" method, if
           that returns something other than undef.

           The XML namespace is also available as $Text::VimColor::NAMESPACE_ID.

       marked()
           This output function returns the marked-up text in the format which the module stores
           it in internally.  The data looks like this:

              use Data::Dumper;
              print Dumper($syntax->marked);

              $VAR1 = [
                 [ 'Statement', 'my' ],
                 [ '', ' ' ],
                 [ 'Identifier', '$syntax' ],
                 [ '', ' = ' ],
                  ...
              ];

           The "marked()" 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 HIGHLIGHTING TYPES section below (or the empty string if none apply), and the
           second is the actual piece of text.

       input_filename()
           Returns the filename of the input file, or undef if a filename wasn't specified.

HIGHLIGHTING TYPES

       The following list gives the names of highlighting types which will be set for pieces of
       text.  For HTML output, these will appear as CSS class names, except that they will all
       have the prefix "syn" added.  For XML output, these will be the names of elements which
       will all be in the namespace "http://ns.laxan.com/text-vimcolor/1".

       Here is the complete list:

       ·   Comment

       ·   Constant

       ·   Identifier

       ·   Statement

       ·   PreProc

       ·   Type

       ·   Special

       ·   Underlined

       ·   Error

       ·   Todo

RELATED MODULES

       These modules allow Text::VimColor to be used more easily in particular environments:

       Apache::VimColor
       Kwiki::VimMode
       Template-Plugin-VimColor

SEE ALSO

       text-vimcolor(1)
           A simple command line interface to this module's features.  It can be used to produce
           HTML and XML output, and can also generate PDF output using an XSLT/XSL-FO stylesheet
           and the FOP processor.

       http://www.vim.org/
           Everything to do with the Vim text editor.

       http://ungwe.org/blog/
           The author's weblog, which uses this module.  It is used to make the code samples look
           pretty.

BUGS

       Quite a few, actually:

       ·   Apparently this module doesn't always work if run from within a 'gvim' window,
           although I've been unable to reproduce this so far.  CPAN bug #11555.

       ·   Things can break if there is already a Vim swapfile, but sometimes it seems to work.

       ·   There should be a way of getting a DOM object back instead of an XML string.

       ·   It should be possible to choose between HTML and XHTML, and perhaps there should be
           some control over the DOCTYPE declaration when a complete file is produced.

       ·   With Vim versions earlier than 6.2 there is a 2 second delay each time Vim is run.

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

AUTHOR

       Geoff Richards <qef@laxan.com>

       The Vim script mark.vim is a crufted version of 2html.vim by Bram Moolenaar <Bram@vim.org>
       and David Ne\v{c}as (Yeti) <yeti@physics.muni.cz>.

COPYRIGHT

       Copyright 2002-2006, Geoff Richards.

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.