NAME

Text::WikiText - Converting WikiText markup to other formats

SYNOPSIS

        use Text::WikiText;

        print Text::WikiText->new->convert(\*STDIN, format => 'Latex');

or

        use Text::WikiText;
        use Text::WikiText::Output::HTML;

        my $parser = Text::WikiText->new;
        my $document = $parser->parse(\*STDIN);

        my $html = Text::WikiText::Output::HTML->new->dump($document);
        print $html;

DESCRIPTION

The WikiText markup specification (and its source in WikiText) may be found at:

  http://podius.wox.org/documentation/wikitext-spec.html
  http://podius.wox.org/documentation/wikitext-spec.txt

Text::WikiText provides a parser for the WikiText markup language, and output modules to convert parsed documents into other markup languages, such as HTML, Latex or Pod.

METHODS

The following methods are available:

new, parse, convert.

new

Create a new WikiText parser object.

parse handle

parse string

Parse a WikiText document from an IO::Handle or a string variable. The function returns the parsed document as a tree structure as defined below.

convert handle [options]

convert string [options]

Parse and convert a WikiText document. This method uses parse to parse a WikiText document and immediately converts it to the specified output format.

The options parameter is a hash reference specifying the output format and various output options.

format

Specifies the output format. Valid options are HTML and Latex. Defaults to HTML.

full_page

Specifies whether the outputted string should be a full document, or an embeddable document part. This options decides whether the output module should generate document headers and footers. Defaults to 0 (omit document headers and footers).

title

author

Specifies the output document title and author. The values are used only when full_page is set. Defaults are undefined.

heading_offset

Specifies an optional offset applied to the level of all headings. An offset of 1 will convert level 1 headings to level 2, level 2 headings to level 3, etc. This option is useful when the output is embedded into other documents. Defaults to 0.

no_verbatim

Specifies whether verbatim blocks should be omitted from the output. Verbatim blocks can break the output document structure and thus should only be allowed from trusted sources. Defaults to 0 (include verbatim blocks).

flat_lists (HTML only)

Specifies whether compact lists include additional paragraph elements. Applies to ul, ol, and dl elements. Defaults to 0 (generate additional paragraph elements).

Example:

        <!-- normal output -->
        <ul>
          <li><p>foo</p></li>
          <li><p>bar</p></li>
        </ul>

        <!-- flat output -->
        <ul>
          <li>foo</li>
          <li>bar</li>
        </ul>

DOCUMENT TREE

Note: The document structure might be redefined in the future.

A parsed WikiText document is an anonymous array of WikiText elements. Each element is an anonymous hash with various properties. All elements have at least the field type, used to identify the type of the element.

Four categories of items are defined:

Sections

SECTION

Fields: level, heading, content.

Environments

QUOTE, LISTING, ENUMERATION, DESCRIPTION.

Fields: content.

Paragraphs

TABLE, RULE, P, PRE, CODE, COMMENT, VERBATIM.

Fields: text (all but TABLE and RULE), content (TABLE only).

Formatting elements

EMPHASIS, STRONG, UNDERLINE, STRIKE, TYPEWRITER, LINK, TEXT, VERBATIM.

Fields: text.

Sections can contain other sections, environments and paragraphs. Environments can contain other environments and paragraphs. Paragraphs can contain formatting elemens. Formatting elements contain plain text.

AUTHORS

Enno Cramer, Mikhael Goikhman

SEE ALSO

wikitext-convert, Text::WikiText::InputFilter, Text::WikiText::Output.