1HTML::WikiConverter(3)User Contributed Perl DocumentationHTML::WikiConverter(3)
2
3
4

NAME

6       HTML::WikiConverter - Convert HTML to wiki markup
7

SYNOPSIS

9         use HTML::WikiConverter;
10         my $wc = new HTML::WikiConverter( dialect => 'MediaWiki' );
11         print $wc->html2wiki( html => '<b>text</b>' ), "\n\n";
12
13         # A more complete example
14
15         my $html = qq(
16           <p><i>Italic</i>, <b>bold</b>, <span style="font-weight:bold">also bold</span>, etc.</p>
17         );
18
19         my @dialects = HTML::WikiConverter->available_dialects;
20         foreach my $dialect ( @dialects ) {
21           my $wc = new HTML::WikiConverter( dialect => $dialect );
22           my $wiki = $wc->html2wiki( html => $html );
23           printf "The %s dialect gives:\n\n%s\n\n", $dialect, $wiki;
24         }
25

DESCRIPTION

27       "HTML::WikiConverter" is an HTML to wiki converter. It can convert HTML
28       source into a variety of wiki markups, called wiki "dialects". The
29       following dialects are supported:
30
31         DokuWiki
32         Kwiki
33         MediaWiki
34         MoinMoin
35         Oddmuse
36         PbWiki
37         PhpWiki
38         PmWiki
39         SlipSlap
40         TikiWiki
41         UseMod
42         WakkaWiki
43         WikkaWiki
44
45       Note that while dialects usually produce satisfactory wiki markup, not
46       all features of all dialects are supported. Consult individual
47       dialects' documentation for details of supported features. Suggestions
48       for improvements, especially in the form of patches, are very much
49       appreciated.
50

METHODS

52   new
53         my $wc = new HTML::WikiConverter( dialect => $dialect, %attrs );
54
55       Returns a converter for the specified wiki dialect. Croaks if $dialect
56       is not provided or its dialect module is not installed on your system.
57       Additional attributes may be specified in %attrs; see "ATTRIBUTES" for
58       a complete list.
59
60   html2wiki
61         $wiki = $wc->html2wiki( $html, %attrs );
62         $wiki = $wc->html2wiki( html => $html, %attrs );
63         $wiki = $wc->html2wiki( file => $file, %attrs );
64         $wiki = $wc->html2wiki( uri => $uri, %attrs );
65
66       Converts HTML source to wiki markup for the current dialect. Accepts
67       either an HTML string $html, an file $file, or a URI <$uri> to read
68       from.
69
70       Attributes assigned in %attrs (see "ATTRIBUTES") will augment or
71       override previously assigned attributes for the duration of the
72       "html2wiki()" call.
73
74   elem_search_lineage
75         my $ancestor = $wc->elem_search_lineage( $node, \%rules );
76
77       Searches the lineage of $node and returns the first ancestor node that
78       has rules matching those specified in %rules, or "undef" if no matching
79       node is found.
80
81       For example, to find out whether $node has an ancestor with rules
82       matching "{ block =>1 }", one could use:
83
84         if( $wc->elem_search_lineage( $node, { block => 1 } ) ) {
85           # do something
86         }
87
88   given_html
89         my $html = $wc->given_html;
90
91       Returns the HTML passed to or fetched (ie, from a file or URI) by the
92       last "html2wiki()" method call. Useful for debugging.
93
94   parsed_html
95         my $parsed_html = $wc->parsed_html;
96
97       Returns a string containing the post-processed HTML from the last
98       "html2wiki" call. Post-processing includes parsing by
99       HTML::TreeBuilder, CSS normalization by
100       HTML::WikiConverter::Normalizer, and calls to the "preprocess" and
101       "preprocess_tree" dialect methods.
102
103   available_dialects
104         my @dialects = HTML::WikiConverter->available_dialects;
105
106       Returns a list of all available dialects by searching the directories
107       in @INC for "HTML::WikiConverter::" modules.
108
109   rules_for_tag
110         my $rules = $wc->rules_for_tag( $tag );
111
112       Returns the rules that will be used for converting elements of the
113       given tag. Follows "alias" references. Note that the rules used for a
114       particular tag may depend on the current set of attributes being used.
115

ATTRIBUTES

117       You may configure "HTML::WikiConverter" using a number of attributes.
118       These may be passed as arguments to the "new" constructor, or can be
119       called as object methods on an H::WC object.
120
121       Some dialects allow other attributes in addition to those below, and
122       may override the attributes' default values. Consult the dialect's
123       documentation for details.
124
125   base_uri
126       URI to use for converting relative URIs to absolute ones. This
127       effectively ensures that the "src" and "href" attributes of image and
128       anchor tags, respectively, are absolute before converting the HTML to
129       wiki markup, which is necessary for wiki dialects that handle internal
130       and external links separately. Relative URIs are only converted to
131       absolute ones if the "base_uri" argument is present. Defaults to
132       "undef".
133
134   dialect
135       (Required) Dialect to use for converting HTML into wiki markup. See the
136       "DESCRIPTION" section above for a list of dialects. "new()" will fail
137       if the dialect given is not installed on your system. Use
138       "available_dialects()" to list installed dialects.
139
140   encoding
141       Specifies the encoding used by the HTML to be converted. Also
142       determines the encoding of the wiki markup returned by the "html2wiki"
143       method. Defaults to "utf8".
144
145   escape_entities
146       Passing "escape_entities" a true value uses HTML::Entities to encode
147       potentially unsafe '<', '>', and '&' characters.  Defaults to true.
148
149   p_strict
150       Boolean indicating whether HTML::TreeBuilder will use strict handling
151       of paragraph tags when parsing HTML input. (This corresponds to the
152       "p_strict" method in the HTML::TreeBuilder module.) Enabled by default.
153
154   passthrough_naked_tags
155       Boolean indicating whether tags with no attributes ("naked" tags)
156       should be removed and replaced with their content. By default, this
157       only applies to non-semantic tags such as <span>, <div>, etc., but does
158       not apply to semantic tags such as <strong>, <address>, etc. To
159       override this behavior and specify the tags that should be considered
160       for passthrough, provide this attribute with a reference to an array of
161       tag names.  Defaults to false, but you'll probably want to enable it.
162
163   preprocess
164       Code reference that gets invoked after HTML is parsed but before it is
165       converted into wiki markup. The callback is passed two arguments: the
166       "HTML::WikiConverter" object and a HTML::Element pointing to the root
167       node of the HTML tree created by HTML::TreeBuilder.
168
169   slurp
170       Boolean that, if enabled, bypasses "HTML::Parser"'s incremental parsing
171       (thus slurping the file in all at once) of files when reading HTML
172       files. If File::Slurp is installed, its "read_file()" function will be
173       used to perform slurping; otherwise, a common Perl idiom will be used
174       for slurping instead. This option is only used if you call
175       "html2wiki()" with the "file" argument.
176
177   strip_empty_tags
178       Strips elements containing no content (unless those elements
179       legitimately contain no content, such as is the case for "br" and "img"
180       tags, for example). Defaults to false.
181
182   strip_tags
183       A reference to an array of tags to be removed from the HTML input prior
184       to conversion to wiki markup. Tag names are the same as those used in
185       HTML::Element. Defaults to "[ '~comment', 'head', 'script', 'style' ]".
186
187   user_agent
188       Specifies the LWP::UserAgent object to be used when fetching the URI
189       passed to "html2wiki()". If unspecified and "html2wiki()" is passed a
190       URI, a default user agent will be created.
191
192   wiki_uri
193       Takes a URI, regular expression, or coderef (or a reference to an array
194       of elements of these types) used to determine which links are to wiki
195       pages: a link whose "href" parameter matches "wiki_uri" will be treated
196       as a link to a wiki page. In addition, "wiki_uri" will be used to
197       extract the title of the wiki page. The way this is done depends on
198       whether the "wiki_uri" has been set to a string, regexp, or coderef.
199       The default is "undef", meaning that all links will be treated as
200       external links by default.
201
202       If "wiki_uri" is a string, it is interpreted as a URI template, and it
203       will be assumed that URIs to wiki pages are created by joining
204       "wiki_uri" with the wiki page title. For example, the English Wikipedia
205       might use "http://en.wikipedia.org/wiki/" as the value of "wiki_uri".
206       Ward's wiki might use "http://c2.com/cgi/wiki?". These examples use an
207       absolute "wiki_uri", but a relative URI can be used as well; an
208       absolute URI will be created based on the value of "base_uri". For
209       example, the Wikipedia example above can be rewritten using "base_uri"
210       of "http://en.wikipedia.org" and a "wiki_uri" of "/wiki/".
211
212       "wiki_uri" can also be a regexp that matches URIs to wiki pages and
213       also extracts the page title from them. For example, the English
214       Wikipedia might use
215       "qr~http://en\.wikipedia\.org/w/index\.php\?title\=([^&]+)~".
216
217       "wiki_uri" can also be a coderef that takes the current
218       "HTML::WikiConverter" object and a URI object. It should return the
219       title of the wiki page extracted from the URI, or "undef" if the URI
220       doesn't represent a link to a wiki page.
221
222       As mentioned above, the "wiki_uri" attribute can either take a single
223       URI/regexp/coderef element or it may be assigned a reference to an
224       array of any number of these elements. This is useful for wikis that
225       have different ways of creating links to wiki pages. For example, the
226       English Wikipedia might use:
227
228         my $wc = new HTML::WikiConverter(
229           dialect => 'MediaWiki',
230           wiki_uri => [
231             'http://en.wikipiedia.org/wiki/',
232             sub { pop->query_param('title') } # requires URI::QueryParam
233           ]
234         );
235
236   wrap_in_html
237       Helps HTML::TreeBuilder parse HTML fragments by wrapping HTML in
238       "<html>" and "</html>" before passing it through "html2wiki". Boolean,
239       enabled by default.
240

ADDING A DIALECT

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

SEE ALSO

248       HTML::Tree, Convert::Wiki
249

AUTHOR

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

BUGS

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

SUPPORT

261       You can find documentation for this module with the perldoc command.
262
263           perldoc HTML::WikiConverter
264
265       You can also look for information at:
266
267       ·   AnnoCPAN: Annotated CPAN documentation
268
269           <http://annocpan.org/dist/HTML-WikiConverter>
270
271       ·   CPAN Ratings
272
273           <http://cpanratings.perl.org/d/HTML-WikiConverter>
274
275       ·   RT: CPAN's request tracker
276
277           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTML-WikiConverter>
278
279       ·   Search CPAN
280
281           <http://search.cpan.org/dist/HTML-WikiConverter>
282

ACKNOWLEDGEMENTS

284       Thanks to Tatsuhiko Miyagawa for suggesting Bundle::HTMLWikiConverter
285       as well as providing code for the "available_dialects()" class method.
286
287       My thanks also goes to Martin Kudlvasr for catching (and fixing!) a bug
288       in the logic of how HTML files were processed.
289
290       Big thanks to Dave Schaefer for the PbWiki dialect and for the idea
291       behind the new "attributes()" implementation.
292
294       Copyright (c) David J. Iberri, all rights reserved.
295
296       This program is free software; you can redistribute it and/or modify it
297       under the same terms as Perl itself.
298
299
300
301perl v5.32.0                      2020-07-28            HTML::WikiConverter(3)
Impressum