/ 
HTML-FormatExternal-12
River stage one • 3 direct dependents • 8 total dependents
/ HTML::FormatExternal

NAME

HTML::FormatExternal - HTML to text formatting using external programs

DESCRIPTION

This is a collection of the following formatter modules turning HTML into plain text by dumping it through the respective external programs.

HTML::FormatText::Elinks
HTML::FormatText::Links
HTML::FormatText::Netrik
HTML::FormatText::Lynx
HTML::FormatText::W3m
HTML::FormatText::Zen

The module interfaces are compatible with HTML::Formatter modules like HTML::FormatText, but the programs do all the work.

Compatible formatting options are provided where possible, like rightmargin, so just by switching the class you can use a different program (or plain HTML::FormatText) according to personal preference or what you've got.

There's nothing particularly difficult about piping through these programs, but a unified interface hides details like how to set margins and how to force input or output charsets.

FUNCTIONS

Each of the classes above provide the following functions. The XXX in the class names is a placeholder for any of Elinks, Lynx, etc as above.

Formatter Compatible Functions

$text = HTML::FormatText::XXX->format_file ($filename, key=>value,...)
$text = HTML::FormatText::XXX->format_string ($html_string, key=>value,...)

Run the formatter program over a file or string with the given options and return the formatted result as a string. See "OPTIONS" below for available options. For example,

$text = HTML::FormatText::Lynx->format_file ('/my/file.html');

$text = HTML::FormatText::W3m->format_string
  ('<html><body> <p> Hello world! </p </body></html>');
$formatter = HTML::FormatText::XXX->new (key=>value, ...)

Create a formatter object with the given options. In the current implementation an object doesn't do much more than remember the options for future use.

$text = $formatter->format ($tree_or_string)

Run the formatter program the given HTML::TreeBuilder tree or string, using the options in the object, and return the formatted result as a string.

A TreeBuilder tree argument (ie. a HTML::Element) is for compatibility with HTML::Formatter. The tree is simply turned into a string with $tree->as_HTML to pass to the program, so if you've got a string already then give that instead of a tree.

Extra Functions

HTML::FormatText::XXX->program_version ()
HTML::FormatText::XXX->program_full_version ()
$formatter->program_version ()
$formatter->program_full_version ()

Return the version number of the formatter program as reported by its --version or similar option. If the formatter program is not available the return is undef.

program_version is the number alone like "2.8.7dev.10". program_full_version is the entire output, which may include build options, copyright notice, etc.

CHARSETS

A file passed to the formatters is interpreted as the HTML default latin-1, or as the charset specified in a <meta> within the HTML, or as forced by the input_charset option below.

A string should be bytes like a file, not Perl wide chars. (There's some secret experimental encode/decode for wide chars, but better let HTML::Formatter take the lead on how that might work.)

The result string is bytes similarly, encoded in whatever the respective programs produce. This is usually the locale charset but you can force it with the output_charset option to be sure of getting what you want.

OPTIONS

The following options can be given. The defaults are whatever the respective programs do. The programs generally read their config files when dumping, so those defaults and formatting details might follow your personal settings (usually a good thing).

leftmargin => INTEGER
rightmargin => INTEGER

The column numbers for the left and right hand ends of the text. leftmargin 0 means no padding on the left. rightmargin is the text width, so for instance 60 would mean the longest line is 60 characters (inclusive of any leftmargin). These options are compatible with HTML::FormatText.

rightmargin is not necessarily a hard limit. Some of the formatter programs will exceed it in a HTML literal <pre> section, or a run of &nbsp;, or similar.

input_charset => STRING

Force the HTML input to be interpreted as bytes of the given charset, including ignoring any <meta> within the HTML.

output_charset => STRING

Force the text output to be encoded as of the given charset. The program defaults vary, but usually follow the locale.

FUTURE

elinks (from Aug 2008) and netrik can produce ANSI escapes for colours, underline, etc, which might be good for text destined for a tty or further crunching. Perhaps an ansi option could enable that, where possible, but for now it's turned off in those programs to keep the default straightforward.

SEE ALSO

HTML::FormatText::Elinks, HTML::FormatText::Links, HTML::FormatText::Netrik, HTML::FormatText::Lynx, HTML::FormatText::W3m, HTML::FormatText::Zen

HOME PAGE

http://www.geocities.com/user42_kevin/html-formatexternal/index.html

LICENSE

Copyright 2008 Kevin Ryde

HTML-FormatExternal is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

HTML-FormatExternal is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with HTML-FormatExternal. If not, see http://www.gnu.org/licenses/.