From the command line:

    txt2html I<arguments>

  From Scripts:

    use HTML::TextToHTML;

    # create a new object
    my $conv = new HTML::TextToHTML();

    # convert a file
    $conv->txt2html(infile=>[$text_file],
                     outfile=>$html_file,
                     title=>"Wonderful Things",
                     mail=>1,
      ]);

    # reset arguments
    $conv->args(infile=>[], mail=>0);

    # convert a string
    $newstring = $conv->process_chunk($mystring)

It supports headings, tables, lists, simple character markup, and hyperlinking, and is highly customizable. It recognizes some of the apparent structure of the source document (mostly whitespace and typographic layout), and attempts to mark that structure explicitly using HTML. The purpose for this tool is to provide an easier way of converting existing text documents to HTML format, giving something nicer than just whapping the text into a big PRE block.

History

Note that all option-names must match exactly --- no abbreviations are allowed. The argument-keys are expected to have values matching those required for that argument --- whether that be a boolean, a string, a reference to an array or a reference to a hash. These will replace any value for that argument that might have been there before.

DEBUGGING

METHODS

new

    $conv = new HTML::TextToHTML(titlefirst=>1,
        ...
    );

Create a new object with new. If arguments are given, these arguments will be used in invocations of other methods.

See ``OPTIONS'' for the possible values of the arguments.

args

Updates the current arguments/options of the HTML::TextToHTML object. Takes hash of arguments, which will be used in invocations of other methods. See ``OPTIONS'' for the possible values of the arguments.

process_chunk

If there are open tags (such as lists) in the input string, process_chunk will automatically close them, unless you specify not to, with the close_tags option.

    $newstring = $conv->process_chunk($mystring,
                            is_fragment=>1);

If you want this string to be treated as a fragment, and not assumed to be a paragraph, set is_fragment to true. If there is more than one paragraph in the string (ie it contains blank lines) then this option will be ignored.

process_para

If there are open tags (such as lists) in the input string, process_para will automatically close them, unless you specify not to, with the close_tags option.

    $newstring = $conv->process_para($mystring,
                            is_fragment=>1);

If you want this string to be treated as a fragment, and not assumed to be a paragraph, set is_fragment to true.

txt2html

Convert a text file to HTML. Takes a hash of arguments. See ``OPTIONS'' for the possible values of the arguments. Arguments which have already been set with new or args will remain as they are, unless they are overridden.

PRIVATE METHODS

init_our_data

Deal with horizontal rules.

shortline

Deal with short lines.

is_mailheader

Is this a mailheader line?

mailheader

Deal with a mailheader.

mailquote

Deal with quoted mail.

subtract_modes

Subtracts modes listed in $mask from $vector.

paragraph

Detect paragraph indentation.

listprefix

Detect and parse a list item.

startlist

Start a list.

endlist

End N lists

continuelist

Continue a list.

liststuff

Process a list (higher-level method).

get_table_type

Figure out the table type of this table, if any

is_aligned_table

Check if the given paragraph-array is an aligned table

is_pgsql_table

Check if the given paragraph-array is a Postgresql table (the ascii format produced by Postgresql)

A PGSQL table can start with an optional table-caption,

    then it has a row of column headings separated by |
    then it has a row of ------+-----
    then it has one or more rows of column values separated by |
    then it has a row-count (N rows)

is_border_table

Check if the given paragraph-array is a Border table.

A BORDER table can start with an optional table-caption,

    then it has a row of +------+-----+
    then it has a row of column headings separated by |
    then it has a row of +------+-----+
    then it has one or more rows of column values separated by |
    then it has a row of +------+-----+

is_delim_table

Check if the given paragraph-array is a Delimited table.

A DELIM table can start with an optional table-caption, then it has at least two rows which start and end and are punctuated by a non-alphanumeric delimiter.

    | val1 | val2 |
    | val3 | val4 |

tablestuff

Process a table.

make_aligned_table

Make an Aligned table.

make_pgsql_table

Make a PGSQL table.

make_border_table

Make a BORDER table.

make_delim_table

Make a Delimited table.

is_preformatted

Returns true if the passed string is considered to be preformatted.

split_end_explicit_preformat

Modifies the given string, and returns the front preformatted part.

endpreformat

End a preformatted section.

preformat

Detect and process a preformatted section.

make_new_anchor

Make a new anchor.

anchor_mail

Make an anchor for a mail section.

anchor_heading

Make an anchor for a heading.

heading_level

Add a new heading style if this is a new heading style.

is_ul_list_line

Tests if this line starts a UL list item.

is_heading

Tests if this line is a heading. Needs to take account of the next line, because a standard heading is defined by ``underlining'' the text of the heading.

heading

Make a heading. Assumes is_heading is true.

is_custom_heading

Check if the given line matches a custom heading.

custom_heading

Make a custom heading. Assumes is_custom_heading is true.

unhyphenate_para

Join up hyphenated words that are split across lines.

tagline

Put the given tag around the given line.

iscaps

Check if a line is all capitals.

caps

Detect and deal with an all-caps line.

do_delim

Deal with a line which has words delimited by the given delimiter; this is used to deal with italics, bold and underline formatting.

glob2regexp

Convert very simple globs to regexps

add_regexp_to_links_table

Add the given regexp ``link definition'' to the links table.

add_literal_to_links_table

Add the given literal ``link definition'' to the links table.

add_glob_to_links_table

Add the given glob ``link definition'' to the links table.

parse_dict

Parse the dictionary file. (see also load_dictionary_links, for things that were stripped)

setup_dict_checking

Set up the dictionary checking.

in_link_context

Check if we are inside a link (<a ...>); certain kinds of substitution are not allowed here.

apply_links

Apply links and formatting to this paragraph.

check_dictionary_links

Check (and alter if need be) the bits in this line matching the patterns in the link dictionary.

load_dictionary_links

Load the dictionary links.

do_file_start

Extra stuff needed for the beginning: HTML headers, and prepending a file if desired.

do_init_call

Certain things, like reading link dictionaries, need to be done only once.

FILE FORMATS

Link Dictionary

This takes the whole pattern as the href, and the resultant link has the same thing in the href as in the contents of the anchor.

But sometimes the href isn't the whole pattern.

    /<URL:\s*(\S+?)\s*>/ --> $1

With the above regex, a () grouping marks the first subexpression, which is represented as $1 (rather than $& the whole expression). This entry matches a URL which was marked explicity as a URL with the pattern <URL:foo> (note the &lt; is shown as the entity, not the actual character. This is because by the time the links dictionary is checked, all such things have already been converted to their HTML entity forms, unless, of course, the escape_HTML_chars option was turned off) This would give us a link in the form <A HREF=``foo''>&lt;URL:foo&gt;</A>

The h flag

However, if we want more control over the way the link is constructed, we can construct it ourself. If one gives the h flag, then the ``result'' part of the entry is taken not to contain the href part of the link, but the whole link.

For example, the entry:

    /&lt;URL:\s*(\S+?)\s*&gt;/ -h-> <A HREF="$1">$1</A>

will take <URL:foo> and give us <A HREF=``foo''>foo</A>

However, this is a very powerful mechanism, because it can be used to construct custom tags which aren't links at all. For example, to flag *italicised words* the following entry will surround the words with EM tags.

    /\B\*([a-z][a-z -]*[a-z])\*\B/ -hi-> <EM>$1</EM>

The i flag

This turns on ignore case in the pattern matching.

The e flag

This turns on execute in the pattern substitution. This really only makes sense if h is turned on too. In that case, the ``result'' part of the entry is taken as perl code to be executed, and the result of that code is what replaces the pattern.

The o flag

This marks the entry as a once-only link. This will convert the first instance of a matching pattern, and ignore any others further on.

For example, the following pattern will take the first mention of HTML::TextToHTML and convert it to a link to the module's home page.

But the following does not have a header:

    I am not a head Man, man
    I am Head Man
    -------------

Tables require a more rigid convention. A table must be marked as a separate paragraph, that is, it must be surrounded by blank lines. Tables come in different types. For a table to be parsed, its --table_type option must be on, and the --make_tables option must be true.

ALIGN Table Type

Columns must be separated by two or more spaces (this prevents accidental incorrect recognition of a paragraph where interword spaces happen to line up). If there are two or more rows in a paragraph and all rows share the same set of (two or more) columns, the paragraph is assumed to be a table. For example

    -e  File exists.
    -z  File has zero size.
    -s  File has nonzero size (returns size).

becomes

    <table>
    <tr><td>-e</td><td>File exists.</td></tr>
    <tr><td>-z</td><td>File has zero size.</td></tr>
    <tr><td>-s</td><td>File has nonzero size (returns size).</td></tr>
    </table>

This guesses for each column whether it is intended to be left, centre or right aligned.

BORDER Table Type

This table type has nice borders around it, and will be rendered with a border, like so:

    +---------+---------+
    | Column1 | Column2 |
    +---------+---------+
    | val1    | val2    |
    | val3    | val3    |
    +---------+---------+

The above becomes

    <table border="1">
    <thead><tr><th>Column1</th><th>Column2</th></tr></thead>
    <tbody>
    <tr><td>val1</td><td>val2</td></tr>
    <tr><td>val3</td><td>val3</td></tr>
    </tbody>
    </table>

It can also have an optional caption at the start.

         My Caption
    +---------+---------+
    | Column1 | Column2 |
    +---------+---------+
    | val1    | val2    |
    | val3    | val3    |
    +---------+---------+

PGSQL Table Type

This format of table is what one gets from the output of a Postgresql query.

     Column1 | Column2
    ---------+---------
     val1    | val2
     val3    | val3
    (2 rows)

This can also have an optional caption at the start. This table is also rendered with a border and table-headers like the BORDER type.

DELIM Table Type

This table type is delimited by non-alphanumeric characters, and has to have at least two rows and two columns before it's recognised as a table.

This one is delimited by the '| character:

    | val1  | val2  |
    | val3  | val3  |

But one can use almost any suitable character such as : # $ % + and so on. This is clever enough to figure out what you are using as the delimiter if you have your data set up like a table. Note that the line has to both begin and end with the delimiter, as well as using it to separate values.

This can also have an optional caption at the start.

    use HTML::TextToHTML;

Create a new object

    my $conv = new HTML::TextToHTML(title=>"Wonderful Things",
                            default_link_dict=>$my_link_file,
      );

Add further arguments

Convert a file

Make a pipleline

• If the underline used to mark a header is off by more than 1, then that part of the text will not be picked up as a header unless you change the value of --underline_length_tolerance and/or --underline_offset_tolerance. People tend to forget this.

REQUIRES

For installation, it needs:

    Module::Build

The txt2html script needs:

    Getopt::Long
    Getopt::ArgvFile
    Pod::Usage
    File::Basename

For testing, it also needs:

    Test::More

For debugging, it also needs:

    YAML::Syck

INSTALLATION

Some of those modules come standard with more recent versions of perl, but I thought I'd mention them anyway, just in case you may not have them.

If you don't know how to install these, try using the CPAN module, an easy way of auto-installing modules from the Comprehensive Perl Archive Network, where the above modules reside. Do ``perldoc perlmodinstall'' or ``perldoc CPAN'' for more information.

To install this module type the following:

   perl Build.PL
   ./Build
   ./Build test
   ./Build install

Or, if you're on a platform (like DOS or Windows) that doesn't like the ``./'' notation, you can do this:

   perl Build.PL
   perl Build
   perl Build test
   perl Build install

In order to install somewhere other than the default, such as in a directory under your home directory, like ``/home/fred/perl'' go

   perl Build.PL --install_base /home/fred/perl

as the first step instead.

This will install the files underneath /home/fred/perl.

You will then need to make sure that you alter the PERL5LIB variable to find the modules, and the PATH variable to find the script.

Therefore you will need to change: your path, to include /home/fred/perl/script (where the script will be)

        PATH=/home/fred/perl/script:${PATH}

the PERL5LIB variable to add /home/fred/perl/lib

        PERL5LIB=/home/fred/perl/lib:${PERL5LIB}

Note that the system links dictionary will be installed as ``/home/fred/perl/share/txt2html/txt2html.dict''

If you want to install in a temporary install directory (such as if you are building a package) then instead of going

   perl Build install

go

   perl Build install destdir=/my/temp/dir

and it will be installed there, with a directory structure under /my/temp/dir the same as it would be if it were installed plain. Note that this is NOT the same as setting --install_base, because certain things are done at build-time which use the install_base info.

See ``perldoc perlrun'' for more information on PERL5LIB, and see ``perldoc Module::Build'' for more information on installation options.

Copyright (c) 2002-2005 by Kathryn Andersen

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