TEXT-VIMCOLOR(1)

📦
version 0.29 · 2 versions
, in fedora 43

💅 TEXT-VIMCOLOR — the manual, but make it cute

okay bestie, this one lives in the User Contributed Perl Documentation section of your manual pages, and it's literally called text-vimcolor. Come sit, we're gonna make Vim paint your files in pretty colors from the command line. 🎀

✨ VERSION ✨

version 0.29 — that's the one, no cap. 💖

🌸 SYNOPSIS 🌸

here's the vibe, copy-paste ready:

$ text-vimcolor FILENAME
  # (like a colored "cat" (same as "text-vimcolor --format ansi FILENAME"))
$ text-vimcolor --format html --full-page FILENAME > OUTPUT.html
$ text-vimcolor --format xml FILENAME > OUTPUT.xml
$ text-vimcolor --format pdf FILENAME --output OUTPUT.pdf

like. it's a cat that went to art school. 💅

🦋 DESCRIPTION 🦋

so basically: this program uses the Vim text editor to highlight text according to its syntax, and then turns that highlighting into ANSI, HTML, XML or PDF output. It works with any file type that Vim itself can highlight. Usually Vim will auto-detect the file format based on the filename (and sometimes it peeks at the contents of the file too, nosy queen 👀).

Exactly one filename should be given on the command line to name the input file. If you give none, the input gets read from STDIN instead. one file. that's the rule. 🫶

If Vim can't guess the file type automatically, you can just tell it explicitly with the --filetype option. For example:

$ text-vimcolor --format html --filetype prolog foo.pl > foo.html

And real talk: this program is a command line interface to the Perl module Text::VimColor. slay. ✨

💖 OPTIONS 💖

here's everything it understands, no skipping, we do not gatekeep here:

  • --help — shows you a summary of the usage, including a list of options. the "what does this even do" button. 🙈
  • --debug — turns on debugging in the underlying Perl module. This makes it print the command used to run Vim. so you can see the receipts. 🧾
  • --all-syntax-groups — enables additional syntax groups instead of just the primary ones. See all_syntax_groups in Text::VimColor for more information. more groups, more drama, more color. 👑
  • --filetype file-type — set the type of the file explicitly. The file-type argument should be something which Vim will recognize when set with its filetype option. Examples are perl, cpp (for C++) and sh (for Unix shell scripts). These names are case sensitive, and should usually be all-lowercase. lowercase bestie, always. 🔤
  • --format output-format — the output format to generate. Must be one of the following:
    • ansi — output text marked up with ANSI escape sequences (using Term::ANSIColor). This is like a colorized version of cat(1).

You can alter the color scheme using the TEXT_VIMCOLOR_ANSI environment variable in the format of SynGroup=color;. For example:

TEXT_VIMCOLOR_ANSI='Comment=green;Statement = magenta; '

On windows the script will attempt to load Win32::Console::ANSI if the output is to STDOUT in an attempt to make the output more useful. You can disable this by setting TEXT_VIMCOLOR_NO_WIN32_ANSI=1.

  • html — generate XHTML output, with text marked with <span> elements with class attributes. A CSS stylesheet should be used to define the coloring, etc., for the output. See the --full-page option below. 💅
  • xml — output is in a simple XML vocabulary. This can then be used by other software to do further transformations (e.g., using XSLT).
  • pdf — XML output is generated and fed to the FOP XSL-FO processor, with an appropriate XSL style sheet. The stylesheet uses XSLT to transform the normal XML output into XSL-FO, which is then rendered to PDF. For this to work, the command fop must be available. An output file must be specified with --output with this format. (yes, fop has to exist. we'll get to the ✨bugs✨ section, don't worry.)

Full details of the HTML and XML output formats can be found in the documentation for Text::VimColor.

  • --output output-filename — specifies the name of the output file. If this option is omitted, the output will be sent to <STDOUT>. This option is required when the output format is PDF (because of limitations in FOP). okay so for PDF you literally have to use this. no exceptions. 🚨
  • --full-page — when the output format is HTML, this option will make the output a complete HTML page, rather than just a fragment of HTML. A CSS stylesheet will be inserted inline into the output, so the output will be usable as it is. full page, full serve. 🍽️
  • --no-inline-stylesheet — when the output format is HTML and --fullpage is given, a stylesheet is normally inserted in-line in the output file. If this option is given it will instead be referenced with a <link> element. linking instead of embedding, we love a modular girlie. 🔗
  • --let name=value — when Vim is run the value of name will be set to value using Vim's let command. More than one of these options can be set. The value is not quoted or escaped in any way, so it can be an expression. These settings take precedence over --unlet options.

This option corresponds to the vim_let setting and method in the Perl module.

  • --unlet name — prevent the value of name being set with Vim's let command. This can be used to turn off default settings.

This option corresponds to the vim_let setting and method in the Perl module, when used with a value of undef.

💀 BUGS 💀

not me exposing the flaws, but we keep it honest:

  • The PDF output option often doesn't work, because it is dependent on FOP, which often doesn't work. This is also why it is mind numbingly slow. 😭 like. genuinely painful. set your expectations accordingly.
  • FOP (0.20.3) seems to ignore the background-color property on <fo:inline>. If that's what it's meant to do, how do you set the background color on part of a line? girl. we don't know either. 🫠

👀 SEE ALSO 👀

  • Text::VimColor — the whole reason any of this works, iykyk. 💜

🫶 AUTHORS 🫶

giving credit where it's soooo due:

  • Geoff Richards <qef@laxan.com>
  • Randy Stauner <rwstauner@cpan.org>

the legal bit, but make it cute:

This software is copyright (c) 2002-2006 by Geoff Richards.

This software is copyright (c) 2011 by Randy Stauner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in freedom bestie, go wild. 🦋

and that's the whole page, periodt. 🌈 this one's from perl v5.42.0, dated 2025-07-25 — so like, still iconic, still current. go color something pretty. ✨💖🎀

📦 where this page comes from