.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "HTML::FromText 3pm"
.TH HTML::FromText 3pm "2020-12-28" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
HTML::FromText \- converts plain text to HTML
.SH "VERSION"
.IX Header "VERSION"
version 2.07
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use HTML::FromText;
\&    text2html( $text, %options );
\&
\&    # or
\&
\&    use HTML::FromText ();
\&    my $t2h  = HTML::FromText\->new( \e%options );
\&    my $html = $t2h\->parse( $html );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`HTML::FromText\*(C'\fR converts plain text to \s-1HTML.\s0 There are a handful of
options that shape the conversion. There is a utility function,
\&\f(CW\*(C`text2html\*(C'\fR, that's exported by default. This function is simply a short\-
cut to the Object Oriented interface described in detail below.
.SH "METHODS"
.IX Header "METHODS"
.SS "new"
.IX Subsection "new"
.Vb 11
\&    my $t2h = HTML::FromText\->new({
\&        paras      => 1,
\&        blockcode  => 1,
\&        tables     => 1,
\&        bullets    => 1,
\&        numbers    => 1,
\&        urls       => 1,
\&        email      => 1,
\&        bold       => 1,
\&        underline  => 1,
\&    });
.Ve
.PP
Constructs a new \f(CW\*(C`HTML::FromText\*(C'\fR object using the given
configuration. The resulting object can parse lots of objects using the
\&\f(CW\*(C`parse\*(C'\fR method.
.PP
Options to \f(CW\*(C`new\*(C'\fR are passed by name, with the value being either true
or false. If true, the option will be turned on. If false, it will be
turned off.  The following outlines all the options.
.PP
Decorators
.IX Subsection "Decorators"
.IP "metachars" 5
.IX Item "metachars"
This option is on by default.
.Sp
All characters that are unsafe for \s-1HTML\s0 display will be encoded using
\&\f(CW\*(C`HTML::Entities::encode_entities()\*(C'\fR.
.IP "urls" 5
.IX Item "urls"
This option is off by default.
.Sp
Replaces URLs with links.
.IP "email" 5
.IX Item "email"
This option is off by default.
.Sp
Replaces email addresses with \f(CW\*(C`mailto:\*(C'\fR links.
.IP "bold" 5
.IX Item "bold"
This option is off by default.
.Sp
Replaces text surrounded by asterisks (\f(CW\*(C`*\*(C'\fR) with the same text
surrounded by \f(CW\*(C`strong\*(C'\fR tags.
.IP "underline" 5
.IX Item "underline"
This option is off by default.
.Sp
Replaces text surrownded by underscores (\f(CW\*(C`_\*(C'\fR) with the same text
surrounded by \f(CW\*(C`span\*(C'\fR tags with an underline style.
.PP
Output Modes
.IX Subsection "Output Modes"
.PP
The following are three output modes and the options associated with
them. They are listed in order of precidence. If none of these modes are
supplied, the basic decorators are applied to the text in whole.
.IP "\fBpre\fR" 5
.IX Item "pre"
This option is off by default.
.Sp
Wraps the entire text in \f(CW\*(C`pre\*(C'\fR tags.
.IP "\fBlines\fR" 5
.IX Item "lines"
This option is off by default.
.Sp
Preserves line breaks by inserting \f(CW\*(C`br\*(C'\fR tags at the end of each line.
.Sp
This mode has further options.
.RS 5
.IP "spaces" 5
.IX Item "spaces"
This option is off by default.
.Sp
All spaces are \s-1HTML\s0 encoded.
.RE
.RS 5
.RE
.IP "\fBparas\fR" 5
.IX Item "paras"
This option is off by default.
.Sp
Preserves paragraphs by wrapping them in \f(CW\*(C`p\*(C'\fR tags.
.Sp
This mode has further options.
.RS 5
.IP "bullets" 5
.IX Item "bullets"
This option is off by default.
.Sp
Convert bulleted lists into unordered lists (\f(CW\*(C`ul\*(C'\fR). Bullets can be
either an asterisk (\f(CW\*(C`*\*(C'\fR) or a hyphen (\f(CW\*(C`\-\*(C'\fR). Lists can be nested.
.IP "numbers" 5
.IX Item "numbers"
This option is off by default.
.Sp
Convert numbered lists into ordered lists (\f(CW\*(C`ol\*(C'\fR). Numbered lists are
identified by numerals. Lists may be nested.
.IP "headings" 5
.IX Item "headings"
This option is off by default.
.Sp
Convert paragraphs identified as headings into \s-1HTML\s0 headings at
the appropriate level. The heading \f(CW\*(C`1. Top\*(C'\fR would be heading
level one (\f(CW\*(C`h1\*(C'\fR). The heading \f(CW\*(C`2.5.1. Blah\*(C'\fR would be heading
level three (\f(CW\*(C`h3\*(C'\fR).
.IP "title" 5
.IX Item "title"
This option is off by default.
.Sp
Convert the first paragraph to a heading level one (\f(CW\*(C`h1\*(C'\fR).
.IP "tables" 5
.IX Item "tables"
This option is off by default.
.Sp
Convert paragraphs identified as tables to \s-1HTML\s0 tables. Tables are two
or more rows and two or more columns. Columns should be separated by two
or more spaces.
.RE
.RS 5
.Sp
The following options apply specifically to indented paragraphs. They
are listed in order of precidence.
.IP "blockparas" 5
.IX Item "blockparas"
This option is off by default.
.Sp
Convert indented paragraphs to block quotes using the \f(CW\*(C`blockquote\*(C'\fR tag.
.IP "blockquotes" 5
.IX Item "blockquotes"
Convert indented paragraphs as \f(CW\*(C`blockparas\*(C'\fR would, but also preserving
line breaks.
.IP "blockcode" 5
.IX Item "blockcode"
Convert indented paragraphs as \f(CW\*(C`blockquotes\*(C'\fR would, but also preserving
spaces using \f(CW\*(C`pre\*(C'\fR tags.
.RE
.RS 5
.RE
.SS "parse"
.IX Subsection "parse"
.Vb 1
\&  my $html = $t2h\->parse( $text );
.Ve
.PP
Parses text supplied as a single scalar string and returns the \s-1HTML\s0 as a
single scalar string.  All the tabs in your text will be expanded using
\&\f(CW\*(C`Text::Tabs::expand()\*(C'\fR.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "text2html"
.IX Subsection "text2html"
.Vb 5
\&    my $html = text2html(
\&                         $text,
\&                         urls  => 1,
\&                         email => 1,
\&                        );
.Ve
.PP
Functional interface that just wraps the \s-1OO\s0 interface. This function is
exported by default. If you don't want it you can \f(CW\*(C`require\*(C'\fR the module
or \f(CW\*(C`use\*(C'\fR it with an empty list.
.PP
.Vb 3
\&    require HTML::FromText;
\&    # or ...
\&    use HTML::FromText ();
.Ve
.SS "Subclassing"
.IX Subsection "Subclassing"
\&\fBNote:\fR At the time of this release, the internals of \f(CW\*(C`HTML::FromText\*(C'\fR
are in a state of development and cannot be expected to stay the same
from release to release. I expect that release version \fB3.00\fR will be
analogous to a \f(CW1.00\fR release of other software. This is because the
current maintainer has rewritten this distribution from the ground up
for the \f(CW\*(C`2.x\*(C'\fR series.  You have been warned.
.PP
The following methods may be used for subclassing \f(CW\*(C`HTML::FromText\*(C'\fR
to create your own text to \s-1HTML\s0 conversions. Each of these methods
is passed just one argument, the object (\f(CW$self\fR), unless
otherwise stated.
.PP
The structure of \f(CW$self\fR is as follows for this release.
.PP
.Vb 8
\&    {
\&     options => {
\&                 option_name => $value,
\&                 ...
\&                },
\&     text    => $text, # as passed to parse(), with tabs expanded
\&     html    => $html, # the HTML that will be returned from parse()
\&    }
.Ve
.PP
\fIpre\fR
.IX Subsection "pre"
.PP
Used when \f(CW\*(C`pre\*(C'\fR mode is specified.
.PP
Should set \f(CW\*(C`$self\->{html}\*(C'\fR.
.PP
Return value is ignored.
.PP
\fIlines\fR
.IX Subsection "lines"
.PP
Used when \f(CW\*(C`lines\*(C'\fR mode is specified.
.PP
Implements the \f(CW\*(C`spaces\*(C'\fR option internally when the option is set to a
true value.
.PP
Should set \f(CW\*(C`$self\->{html}\*(C'\fR.
.PP
Return value is ignored.
.PP
\fIparas\fR
.IX Subsection "paras"
.PP
Used when the \f(CW\*(C`paras\*(C'\fR mode is specified.
.PP
Splits \f(CW\*(C`$self\->{text}\*(C'\fR into paragraphs internally and sets up
\&\f(CW\*(C`$self\->{paras}\*(C'\fR as follows.
.PP
.Vb 7
\&    paras => {
\&              0 => {
\&                    text => $text, # paragraph text
\&                    html => $html, # paragraph html
\&                   },
\&              ... # and so on for all paragraphs
\&             },
.Ve
.PP
Implements the \f(CW\*(C`title\*(C'\fR option internally when the option is turned on.
.PP
Converts any normal paragraphs to \s-1HTML\s0 paragraphs (surrounded by \f(CW\*(C`p\*(C'\fR
tags) internally.
.PP
Should set \f(CW\*(C`$self\->{html}\*(C'\fR.
.PP
Return value is ignored.
.PP
\fIheadings\fR
.IX Subsection "headings"
.PP
Used to format headings when the \f(CW\*(C`headings\*(C'\fR option is turned on.
.PP
Return value is ignored.
.PP
\fIbullets\fR
.IX Subsection "bullets"
.PP
Format bulleted lists when the \f(CW\*(C`bullets\*(C'\fR option is turned on.
.PP
Return value is ignored.
.PP
\fInumbers\fR
.IX Subsection "numbers"
.PP
Format numbered lists when the \f(CW\*(C`numbers\*(C'\fR option is turned on.
.PP
Return value is ignored.
.PP
\fItables\fR
.IX Subsection "tables"
.PP
Format tables when the \f(CW\*(C`tables\*(C'\fR option is turned on.
.PP
Return value is ignored.
.PP
\fIblockparas\fR
.IX Subsection "blockparas"
.PP
Used when the \f(CW\*(C`blockparas\*(C'\fR option is turned on.
.PP
Return value is ignored.
.PP
\fIblockquotes\fR
.IX Subsection "blockquotes"
.PP
Used when the \f(CW\*(C`blockquotes\*(C'\fR option is turned on.
.PP
Return value is ignored.
.PP
\fIblockcode\fR
.IX Subsection "blockcode"
.PP
Used when the \f(CW\*(C`blockcode\*(C'\fR option is turned on.
.PP
Return value is ignored.
.PP
\fIurls\fR
.IX Subsection "urls"
.PP
Turn urls into links when \f(CW\*(C`urls\*(C'\fR option is turned on.
.PP
Should operate on \f(CW\*(C`$self\->{html}\*(C'\fR.
.PP
Return value is ignored.
.PP
\fIemail\fR
.IX Subsection "email"
.PP
Turn email addresses into \f(CW\*(C`mailto:\*(C'\fR links when \f(CW\*(C`email\*(C'\fR option is
turned on.
.PP
Should operate on \f(CW\*(C`$self\->{html}\*(C'\fR.
.PP
Return value is ignored.
.PP
\fIunderline\fR
.IX Subsection "underline"
.PP
Underline things between _underscores_ when \f(CW\*(C`underline\*(C'\fR option is
turned on.
.PP
Should operate on \f(CW\*(C`$self\->{html}\*(C'\fR.
.PP
Return value is ignored.
.PP
\fIbold\fR
.IX Subsection "bold"
.PP
Bold things between *asterisks* when \f(CW\*(C`bold\*(C'\fR option is turned on.
.PP
Should operate on \f(CW\*(C`$self\->{html}\*(C'\fR.
.PP
Return value is ignored.
.PP
\fImetachars\fR
.IX Subsection "metachars"
.PP
Encode meta characters when \f(CW\*(C`metachars\*(C'\fR option is turned on.
.PP
Should operate on \f(CW\*(C`$self\->{html}\*(C'\fR.
.PP
Return value is ignored.
.SS "Output"
.IX Subsection "Output"
The output from \f(CW\*(C`HTML::FromText\*(C'\fR has been updated to pass \s-1XHTML 1.1\s0
validation. Every \s-1HTML\s0 tag that should have a \s-1CSS\s0 class name does. They
are prefixed with \f(CW\*(C`hft\-\*(C'\fR and correspond to the names of the options to
\&\f(CW\*(C`new()\*(C'\fR (or \f(CW\*(C`text2html()\*(C'\fR). For example \f(CW\*(C`hft\-lines\*(C'\fR, \f(CW\*(C`hft\-paras\*(C'\fR,
and \f(CW\*(C`hft\-urls\*(C'\fR.
.PP
One important note is the output for \f(CW\*(C`underline\*(C'\fR. Because the <u> tag
is deprecated in this specification a \f(CW\*(C`span\*(C'\fR is used with a style
attribute of \f(CW\*(C`text\-decoration: underline\*(C'\fR. The class is \f(CW\*(C`hft\-
underline\*(C'\fR. If you want to override the \f(CW\*(C`text\-decoration\*(C'\fR style in the
\&\s-1CSS\s0 class you'll need to do so like this.
.PP
.Vb 1
\&    text\-decoration: none !important;
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBtext2html\fR\|(1).
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Ricardo \s-1SIGNES\s0 <rjbs@cpan.org>
.IP "\(bu" 4
Casey West <casey@geeknest.com>
.IP "\(bu" 4
Gareth Rees <garethr@cre.canon.co.uk>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2003 by Casey West.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.