Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
HTML::WikiConverter(3)User Contributed Perl DocumentatioHTML::WikiConverter(3)

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.

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:

       o   AnnoCPAN: Annotated CPAN documentation

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

       o   CPAN	Ratings

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

       o   RT: CPAN's request tracker

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

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

perl v5.32.1			  2009-03-21		HTML::WikiConverter(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | ATTRIBUTES | ADDING A DIALECT | SEE ALSO | AUTHOR | BUGS | SUPPORT | ACKNOWLEDGEMENTS | COPYRIGHT & LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=HTML::WikiConverter&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help