txt2html [ --append_file filename ] [ --append_head filename ]
    [ --body_deco string ] [ --bold_delimiter string ]
    [ --bullets string ] [ --bullets_ordered string ] [ --caps_tag tag ]
    { --custom_heading_regexp regexp } [ --debug ] [ --demoronize ]
    [ --default_link_dict filename ] [ --dict_debug n ]
    [ --doctype doctype ] [ --eight_bit_clean ] [ --escape_HTML_chars ]
    [ --explicit_headings ] [ --extract ] [ --hrule_min n ]
    [ --indent_width n ] [ --indent_par_break ]
    { --infile filename | --instring string }
    [ --italic_delimiter string ] { --links_dictionaries filename }
    [ --link_only ] [ --lower_case_tags ] [ --mailmode ]
    [ --make_anchors ] [ --make_tables ] [ --min_caps_length n ]
    [ --outfile filename ] [ --par_indent n ]
    [ --preformat_trigger_lines n ] [ --endpreformat_trigger_lines n ]
    [ --preformat_start_marker regexp ] [ --preformat_end_marker regexp ]
    [ --preformat_whitespace_min n ] [ --prepend_file filename ]
    [ --preserve_indent ] [ --short_line_length n ]
    [ --style_url stylesheet_url ] [ --tab_width n ]
    [ --table_type type=0/1 ] [ --title title ] [ --titlefirst ]
    [ --underline_delimiter string ] [ --underline_length_tolerance n ]
    [ --underline_offset_tolerance n ] [ --unhyphenation ]
    [ --use_mosaic_header ] [ --use_preformat_marker ] [ --xhtml ] [file ...]

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.

One can use txt2html as a filter, outputting the result to STDOUT, or to a given file.

One can define options in a config file as well as on the command-line.

See Getopt::Long for more information.

If the Getopt::ArgvFile module is installed, then groups of options can be read from a file or files designated by the @ character preceding the name. For example:

    txt2html @poem_options --outfile poem_glory.html  poem_glory.txt

See ``Options Files'' for more information.

Help options:

General options:

FILE FORMATS

Options Files

    # set options for poetry
    --titlefirst
    --short_line_length 60

See Getopt::ArgvFile for more information.

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

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.

    txt2html --infile thing.txt --outfile thing.html

This will create a HTML file called "thing.html" from the plain text file "thing.txt".

PREREQUISITES

    Pod::Usage
    HTML::TextToHTML
    Getopt::Long
    Getopt::ArgvFile
    File::Basename
    YAML::Syck
    perldoc

SCRIPT CATEGORIES

Copyright (c) 2002-2005 Kathryn Andersen

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