Provided by: libhtml-wikiconverter-perl_0.68-3_all bug

NAME

       HTML::WikiConverter - Convert HTML to wiki markup

SYNOPSIS

         use HTML::WikiConverter;
         my $wc = new HTML::WikiConverter( dialect => 'MediaWiki' );
         print $wc->html2wiki( html => '<b>text</b>' ), "\n\n";

         # A more complete example

         my $html = qq(
           <p><i>Italic</i>, <b>bold</b>, <span style="font-weight:bold">also bold</span>, etc.</p>
         );

         my @dialects = HTML::WikiConverter->available_dialects;
         foreach my $dialect ( @dialects ) {
           my $wc = new HTML::WikiConverter( dialect => $dialect );
           my $wiki = $wc->html2wiki( html => $html );
           printf "The %s dialect gives:\n\n%s\n\n", $dialect, $wiki;
         }

DESCRIPTION

       "HTML::WikiConverter" is an HTML to wiki converter. It can convert HTML source into a
       variety of wiki markups, called wiki "dialects". The following dialects are supported:

         DokuWiki
         Kwiki
         MediaWiki
         MoinMoin
         Oddmuse
         PbWiki
         PhpWiki
         PmWiki
         SlipSlap
         TikiWiki
         UseMod
         WakkaWiki
         WikkaWiki

       Note that while dialects usually produce satisfactory wiki markup, not all features of all
       dialects are supported. Consult individual dialects' documentation for details of
       supported features. Suggestions for improvements, especially in the form of patches, are
       very much appreciated.

       Since version 0.50 all dialects were separated out from HTML:WikiConverter.  Please
       install the independent dialect packages as needed.

METHODS

   new
         my $wc = new HTML::WikiConverter( dialect => $dialect, %attrs );

       Returns a converter for the specified wiki dialect. Croaks if $dialect is not provided or
       its dialect module is not installed on your system. Additional attributes may be specified
       in %attrs; see "ATTRIBUTES" for a complete list.

   html2wiki
         $wiki = $wc->html2wiki( $html, %attrs );
         $wiki = $wc->html2wiki( html => $html, %attrs );
         $wiki = $wc->html2wiki( file => $file, %attrs );
         $wiki = $wc->html2wiki( uri => $uri, %attrs );

       Converts HTML source to wiki markup for the current dialect. Accepts either an HTML string
       $html, an file $file, or a URI <$uri> to read from.

       Attributes assigned in %attrs (see "ATTRIBUTES") will augment or override previously
       assigned attributes for the duration of the "html2wiki()" call.

   elem_search_lineage
         my $ancestor = $wc->elem_search_lineage( $node, \%rules );

       Searches the lineage of $node and returns the first ancestor node that has rules matching
       those specified in %rules, or "undef" if no matching node is found.

       For example, to find out whether $node has an ancestor with rules matching "{ block =>1
       }", one could use:

         if( $wc->elem_search_lineage( $node, { block => 1 } ) ) {
           # do something
         }

   given_html
         my $html = $wc->given_html;

       Returns the HTML passed to or fetched (ie, from a file or URI) by the last "html2wiki()"
       method call. Useful for debugging.

   parsed_html
         my $parsed_html = $wc->parsed_html;

       Returns a string containing the post-processed HTML from the last "html2wiki" call. Post-
       processing includes parsing by HTML::TreeBuilder, CSS normalization by
       HTML::WikiConverter::Normalizer, and calls to the "preprocess" and "preprocess_tree"
       dialect methods.

   available_dialects
         my @dialects = HTML::WikiConverter->available_dialects;

       Returns a list of all available dialects by searching the directories in @INC for
       "HTML::WikiConverter::" modules.

   rules_for_tag
         my $rules = $wc->rules_for_tag( $tag );

       Returns the rules that will be used for converting elements of the given tag. Follows
       "alias" references. Note that the rules used for a particular tag may depend on the
       current set of attributes being used.

ATTRIBUTES

       You may configure "HTML::WikiConverter" using a number of attributes. These may be passed
       as arguments to the "new" constructor, or can be called as object methods on an H::WC
       object.

       Some dialects allow other attributes in addition to those below, and may override the
       attributes' default values. Consult the dialect's documentation for details.

   base_uri
       URI to use for converting relative URIs to absolute ones. This effectively ensures that
       the "src" and "href" attributes of image and anchor tags, respectively, are absolute
       before converting the HTML to wiki markup, which is necessary for wiki dialects that
       handle internal and external links separately. Relative URIs are only converted to
       absolute ones if the "base_uri" argument is present. Defaults to "undef".

   dialect
       (Required) Dialect to use for converting HTML into wiki markup. See the "DESCRIPTION"
       section above for a list of dialects. "new()" will fail if the dialect given is not
       installed on your system. Use "available_dialects()" to list installed dialects.

   encoding
       Specifies the encoding used by the HTML to be converted. Also determines the encoding of
       the wiki markup returned by the "html2wiki" method. Defaults to "utf8".

   escape_entities
       Passing "escape_entities" a true value uses HTML::Entities to encode potentially unsafe
       '<', '>', and '&' characters.  Defaults to true.

   p_strict
       Boolean indicating whether HTML::TreeBuilder will use strict handling of paragraph tags
       when parsing HTML input. (This corresponds to the "p_strict" method in the
       HTML::TreeBuilder module.) Enabled by default.

   passthrough_naked_tags
       Boolean indicating whether tags with no attributes ("naked" tags) should be removed and
       replaced with their content. By default, this only applies to non-semantic tags such as
       <span>, <div>, etc., but does not apply to semantic tags such as <strong>, <address>, etc.
       To override this behavior and specify the tags that should be considered for passthrough,
       provide this attribute with a reference to an array of tag names.  Defaults to false, but
       you'll probably want to enable it.

   preprocess
       Code reference that gets invoked after HTML is parsed but before it is converted into wiki
       markup. The callback is passed two arguments: the "HTML::WikiConverter" object and a
       HTML::Element pointing to the root node of the HTML tree created by HTML::TreeBuilder.

   slurp
       Boolean that, if enabled, bypasses "HTML::Parser"'s incremental parsing (thus slurping the
       file in all at once) of files when reading HTML files. If File::Slurp is installed, its
       "read_file()" function will be used to perform slurping; otherwise, a common Perl idiom
       will be used for slurping instead. This option is only used if you call "html2wiki()" with
       the "file" argument.

   strip_empty_tags
       Strips elements containing no content (unless those elements legitimately contain no
       content, such as is the case for "br" and "img" tags, for example). Defaults to false.

   strip_tags
       A reference to an array of tags to be removed from the HTML input prior to conversion to
       wiki markup. Tag names are the same as those used in HTML::Element. Defaults to "[
       '~comment', 'head', 'script', 'style' ]".

   user_agent
       Specifies the LWP::UserAgent object to be used when fetching the URI passed to
       "html2wiki()". If unspecified and "html2wiki()" is passed a URI, a default user agent will
       be created.

   wiki_uri
       Takes a URI, regular expression, or coderef (or a reference to an array of elements of
       these types) used to determine which links are to wiki pages: a link whose "href"
       parameter matches "wiki_uri" will be treated as a link to a wiki page. In addition,
       "wiki_uri" will be used to extract the title of the wiki page. The way this is done
       depends on whether the "wiki_uri" has been set to a string, regexp, or coderef. The
       default is "undef", meaning that all links will be treated as external links by default.

       If "wiki_uri" is a string, it is interpreted as a URI template, and it will be assumed
       that URIs to wiki pages are created by joining "wiki_uri" with the wiki page title. For
       example, the English Wikipedia might use "http://en.wikipedia.org/wiki/" as the value of
       "wiki_uri". Ward's wiki might use "http://c2.com/cgi/wiki?". These examples use an
       absolute "wiki_uri", but a relative URI can be used as well; an absolute URI will be
       created based on the value of "base_uri". For example, the Wikipedia example above can be
       rewritten using "base_uri" of "http://en.wikipedia.org" and a "wiki_uri" of "/wiki/".

       "wiki_uri" can also be a regexp that matches URIs to wiki pages and also extracts the page
       title from them. For example, the English Wikipedia might use
       "qr~http://en\.wikipedia\.org/w/index\.php\?title\=([^&]+)~".

       "wiki_uri" can also be a coderef that takes the current "HTML::WikiConverter" object and a
       URI object. It should return the title of the wiki page extracted from the URI, or "undef"
       if the URI doesn't represent a link to a wiki page.

       As mentioned above, the "wiki_uri" attribute can either take a single URI/regexp/coderef
       element or it may be assigned a reference to an array of any number of these elements.
       This is useful for wikis that have different ways of creating links to wiki pages. For
       example, the English Wikipedia might use:

         my $wc = new HTML::WikiConverter(
           dialect => 'MediaWiki',
           wiki_uri => [
             'http://en.wikipiedia.org/wiki/',
             sub { pop->query_param('title') } # requires URI::QueryParam
           ]
         );

   wrap_in_html
       Helps HTML::TreeBuilder parse HTML fragments by wrapping HTML in "<html>" and "</html>"
       before passing it through "html2wiki". Boolean, enabled by default.

ADDING A DIALECT

       Consult HTML::WikiConverter::Dialects for documentation on how to write your own dialect
       module for "HTML::WikiConverter". Or if you're not up to the task, drop me an email and
       I'll have a go at it when I get a spare moment.

SEE ALSO

       HTML::Tree, Convert::Wiki

AUTHOR

       David J. Iberri, "<diberri@cpan.org>"

BUGS

       Please report any bugs or feature requests to "bug-html-wikiconverter at rt.cpan.org", or
       through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML-WikiConverter>.  I will be notified,
       and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc HTML::WikiConverter

       You can also look for information at:

       •   AnnoCPAN: Annotated CPAN documentation

           <http://annocpan.org/dist/HTML-WikiConverter>

       •   CPAN Ratings

           <http://cpanratings.perl.org/d/HTML-WikiConverter>

       •   RT: CPAN's request tracker

           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-WikiConverter>

       •   Search CPAN

           <http://search.cpan.org/dist/HTML-WikiConverter>

ACKNOWLEDGEMENTS

       Thanks to Tatsuhiko Miyagawa for suggesting Bundle::HTMLWikiConverter as well as providing
       code for the "available_dialects()" class method.

       My thanks also goes to Martin Kudlvasr for catching (and fixing!) a bug in the logic of
       how HTML files were processed.

       Big thanks to Dave Schaefer for the PbWiki dialect and for the idea behind the new
       "attributes()" implementation.

COPYRIGHT & LICENSE

       Copyright (c) David J. Iberri, all rights reserved.

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