| # ChangeLog for Pod::Simple dist |
| #--------------------------------------------------------------------------- |
| |
| 2012-03-01 David E. Wheeler <david@justatheory.org> |
| * Release 3.20 |
| |
| Removed use of 'done_testing' in t/xhtml15.t, which was added in |
| v3.19. Thanks to Paul Howarth for the catch. |
| |
| Fixed quoting of links in a regular expression Pod::Simple::Text. |
| Reported by Father Chrysostomos. |
| |
| Fix test failure on case-insensitive, non-case-preserving file systems |
| (VMS I'm looking at *you*). Patch from Craig A. Berry. |
| |
| Pod::Simple::HTML no longer emits "href='#___top'" if a TOC |
| (index) is not output. Patch from Rick Myers. |
| |
| Fixed links in the TOC of XHTML output to use IDs derived from encoded |
| text, rather than raw Pod, so that it will link to the ID actually |
| generated for the section. Thanks to Randy Stauner for the report |
| (with test case!) (RT #72544). |
| |
| PullParser now throws an exception on an attempt to set a source |
| more than once. Necessary because data from the previous source |
| will be cached, so the new source would be ignored anyway. Create a |
| new PullParser, instead. Thanks to Paul Boldra for the report (RT |
| #74265). |
| |
| 2011-08-23 David E. Wheeler <david@justatheory.org> |
| * Release 3.19 |
| |
| Fixed occasional test failure when tests are run in parallel |
| (HARNESS_OPTIONS=j6:c). Thanks to Alexei Znamensky for the report and |
| Marc Green for the fix. |
| |
| Added "pod_handler" option. This is a callback that can be used to |
| inspect the content on a "=pod" line. Marc Green/Google Summer of |
| Code. |
| |
| Added tests for proper line-ending parsing from the previous |
| release. The tests were in the repository, but didn't make it into |
| the MANIFEST or, therefore, the release. Reported by Marc Green. |
| |
| Added the "parse_empty_lists" option. When enabled, Pod::Simple |
| will recognize empty lists (that is, a blocks with '=over' and |
| '=back' but nothing in between). Disabled by default. Marc |
| Green/Google Summer of Code. |
| |
| Added the "whiteline_handler" attribute. It's much like |
| "code_handler", "cut_handler", and "pod_handler", except it's |
| triggered on lines that contain only whitespace characters. Marc |
| Green/Google Summer of Code. |
| |
| Added "raw" attribute to L<> treelet that contains the L<>'s raw |
| contents. Marc Green/Google Summer of Code. |
| |
| Pod directives autoclosed by Pod::Simple are now denoted as such |
| by the new "fake_closer" attribue. Marc Green/Google Summer of |
| Code. |
| |
| Fixed incompatibility with Pod::Simple::HTMLBatch in |
| Pod::Simple::XHTML. Patch by Eric Johnson. |
| |
| 2011-07-16 David E. Wheeler <david@justatheory.org> |
| * Release 3.18 |
| |
| Pod::Simple now properly parses Pod files using Mac OS Classic line- |
| endings (\r). Marc Green/Google Summer of Code. |
| |
| Fixed test failure in 't/search50.t when the test finds a .pod but |
| the module is in a .pm. Thanks to the cpan-testers who reported |
| this when the test searched for Capture::Tiny. |
| |
| 2011-07-09 David E. Wheeler <david@justatheory.org> |
| * Release 3.17 |
| |
| Documented tertiary methods. Patch from Shawn H Corey. |
| |
| Added "backlink" option to Pod::Simple::XHTML. Thanks to Marc |
| Green/Google Summer of Code for the pull request. |
| |
| Typos fixed in Pod::Simple::HTMLBatch. Reported by Shawn H Corey. |
| |
| Fixed quoting of value returned by a "strip_verbatim_indent()" |
| code reference so that regex meta characters are properly escaped. |
| |
| Added "anchor_items" option to Pod::Simple::XHMTL. This allows |
| text items (which are output as <dt> elements) to have IDs that |
| can be referenced in the "#" part of a URL. Marc Green/Google |
| Summer of Code. |
| |
| Added "recurse" option to Pod::Simple::Search. It's enabled by |
| default; disable it to turn off recursion into subdirectories. |
| Marc Green/Google Summer of Code. |
| |
| Added documentation to clarify the behavior of the "content_seen" |
| method. Thanks to Olaf Alders for the pull request. |
| |
| 2011-03-14 David E. Wheeler <david@justatheory.org> |
| * Release 3.16 |
| |
| Fixed invalid HTML generated for nested lists by Pod::Simple::XHTML |
| (Fitz Elliott). |
| |
| Replaced the invalid "<nobr>" tag -- created for "S<>" -- with |
| '<span style="white-space: nowrap;">' (Fitz Elliott). |
| |
| Fixed some nerbles in our own Pod (Michael Stevens) |
| |
| Improved the "Minimal code" example in Pod::Simple::HTML. The key |
| is to use pase_file(), not parse_from_file() (which should |
| otherwise be undocumented, and is just there for Pod::Parser |
| compatibility. Thanks to prodding from Ævar Arnfjörð Bjarmason (RT |
| #65428). |
| |
| Added the html_charset() and html_encode_chars() attributes to |
| Pod::Simple::XHTML. Inspired by a bug report from Agent Zhang |
| (章亦春) (RT #29587). |
| |
| Added "Minimal code" example to the Pod::Simple::XHTML documentation. |
| |
| Fixed mispelling of the "=encoding" markup in the parser (it was |
| spelled "=encode"). Thanks to "TTY" for the patch. (RT #24820). |
| |
| 2010-11-11 David E. Wheeler <david@justatheory.org> |
| * Release 3.15 |
| |
| Removed "perlpod.pod" and "perlpodspec.pod". These now just live |
| in the Perl core. |
| |
| Fixed stylesheet names output by HTMLBatch to match the names of |
| the actual stylesheet files (broken in 3.09). Thanks to Kevin Ryde |
| for the report (RT #56725). |
| |
| Added missing closing slash to the CSS links in the XHTML output. |
| Thanks to HarleyPig for the patch! |
| |
| Added parens around bar "qw(...)" in t/xhtml05.t. Thanks to Jerry |
| D. Hedden for the patch. |
| |
| Improved the Pod::Simple::HTML docs. Thanks to Gabor Szabo for the |
| patch. |
| |
| Pod::Simple::XHTML now properly encodes entities in URLs in the |
| anchor tag. Thanks to John McNamara for the report (RT-60249). |
| |
| Pod::Simple::HTML and XHTML now strip whitespace from the end of |
| section names that appear as anchor names for headers (in HTML) |
| and IDs (in XHTML). Such whitespace appeared when "X<>" entities |
| were stripped out but not the space between them (RT-56572). |
| |
| Make test "t/search50.t" always pass on case-insensitive file |
| systems rather than just skip VMS. |
| |
| 2009-04-27 |
| * Release 3.14 |
| |
| Removed explicit loading of UNIVERSAL. RJBS. |
| |
| Reversed the change applied in release 3.09 to fix RT #12239. POD |
| tag found inside a complex POD tag (e.g., "C<<< I<foo> >>>") is |
| again parsed as a tag embedded in a tag instead of text and |
| entities. The previous interpretation of `perldoc perlpod` was |
| mistaken. (RT #55602 from Christopher J. Madsen). |
| |
| 2009-12-17 David E. Wheeler <david@justatheory.org> |
| * Release 3.13 |
| |
| Removed deleted test file from MANIFEST. |
| |
| 2009-12-17 David E. Wheeler <david@justatheory.org> |
| * Release 3.12 |
| |
| Removed "All rights reserved" from all files. |
| |
| Added acknowledgements to man.he.net and search.cpan.org for |
| permission to link man pages and Perl module links to their sites |
| in the output of Pod::Simple::HTML and Pod::Simple::XHTML. |
| |
| Add "html_h_level" option to Pod::Simple::XHTML and ::HTML to allow |
| a =head1 to become an <h2> and so on. RJBS. |
| |
| Add batch_mode_page_object_init() method to Pod::Simple::XHTML. |
| This allows it to be used by Pod::Simple::HTMLBatch. |
| |
| Fixed a regression in Pod::Simple::XHTML where '=begin html' blocks |
| were incorrectly escaped rather than simply passed through unmolested. |
| RJBS. |
| |
| Removed the undocumented "fullstop_space_harden" attribute, which |
| apparently was only used by Pod::Text a very long time ago. |
| |
| 2009-12-09 David E. Wheeler <david@justatheory.org> |
| * Release 3.11 |
| |
| Restored code to HTMLBatch that allows the TOC (index) to be created |
| in batch jobs (RT #52324 from Martin J. Evans). |
| |
| Added resources to META.yml, including bug tracker, license, and |
| repository. |
| |
| Turned man page links into links to man.he.net in Pod::Simple::HTML |
| and Pod::Simple::XHTML output. Subclass and override |
| resolve_man_page_link() to use a different URL. |
| |
| Added the resolve_pod_page_link() and resolve_man_page_link() methods |
| to Pod::Simple::XHTML to make it easier for subclasses to change the |
| URLs created for POD and man page links. |
| |
| Fixed the output of entities in L<> tags by Pod::Simple::XHTML. |
| |
| Fixed the output of POD links from Pod::Simple::XHTML so that the |
| section part (/foo) is turned into a proper fragment identifier (#foo) |
| in the resulting search.cpan.org link. |
| |
| Pod::Simple::Text now outputs URLs for links created in the |
| L<text|URL> format. For example, L<Perl|http://perl.org> is now |
| output as "Perl <http://perl.org>" rather than just as "Perl". |
| |
| Updated perlpod.pod and perlpodspec.pod to sync up with Perl core |
| (and to be released in Perl 5.12). Changes include: |
| * Removing the prohibition against L<text|href> |
| * Deprecation of L<section> and L<"section"> |
| * Legalization of "=begin formatname parameter" |
| |
| A couple of bug fixes in Pod::Simple::HTML from Graham Barr. |
| |
| Added the do_section() method to Pod::Simple::HTML. Graham Barr. |
| |
| Word-smithed the "DESCRIPTION" a bit and wrote the README. |
| |
| Synced up all module version numbers to 3.11 except for |
| Pod::Simple::HTMLLegacy, which is at 5.01 and should not have its |
| version number lowered. |
| |
| 2009-11-12 David E. Wheeler <david@justatheory.org> |
| * Release 3.10 |
| |
| Converted test files that had DOS endings to have Unix endings |
| (RT #50922 from Steve Hay). |
| |
| Skip tests on VMS where the lack of filename case preservation can |
| wreak havoc (RT #51184 from Craig A. Berry). |
| |
| Fix nested definition list format in the XHTML output |
| (RT #51187 from Lars Dɪᴇᴄᴋᴏᴡ). |
| |
| Added some files missing from the MANIFEST (and therefore the |
| distribution) in the last two releases. |
| |
| 2009-10-27 Allison Randal <allison@perl.org> |
| * Release 3.09 |
| |
| Add support for an index (TOC) in the XHTML output from David E. |
| Wheeler. |
| |
| Add strip_verbatim_indent() from David E. Wheeler. |
| |
| Added the "nocase" option to PullParser's get_title(), |
| get_version(), get_description(), and get_author() methods. This |
| allows one to fetch the contents of those sections regardless of |
| the case of the labels (e.g., "NAME" and "Name" and "name" are all |
| valid). Graham Barr. |
| |
| Added the search_class() accessor to Pod::Simple::HTMLBatch. |
| David E. Wheeler. |
| |
| XHTML output now properly encodes entities in all places, not just |
| in verbatim blocks and code spans. David E. Wheeler. |
| |
| Fixed XHTML to output definition lists when it should, rather than |
| (broken) unordered lists. David E. Wheeler. |
| |
| Fixed XHTML so that multiparagraph list items work correctly. |
| David E. Wheeler. |
| |
| Fixed XHTML ordered list output so that it does not include the |
| number specified in the POD in the output. This is on a par with |
| out the HTML output works. David E. Wheeler. |
| |
| Applied URL patch from Leon Brocard for The Perl Journal archives. |
| |
| Fixed test failures with older versions of HTML::Entities (RT #43903 |
| from Salvador Tercia). |
| |
| Changed CSS files generated by HTMLBatch to be no more than 8.3 |
| characters long. (RT #40450 from Renee Baecker) |
| |
| Added entity handling for E<sol> and E<verbar> to Pod::Simple::XHTML. |
| (RT #49615 from Chas Owens.) |
| |
| Fixed a bug in Pod::Simple::HTML where a definition term item with |
| no corresponding definition item would be output with no closing |
| </a></dt>. (RT # 37107 from Kevin Ryde). |
| |
| Added entity handling for numeric entities to Pod::Simple::XHTML, |
| following perlpod specification. |
| |
| A POD tag found inside a complex POD tag (e.g., "C<<< C<foo> >>>") |
| is now properly parsed as text and entities instead of a tag |
| embedded in a tag. This is in compliance with `perldoc perlpod` |
| (RT #12239 from Michael Schwern). |
| |
| Thanks to David E. Wheeler for applying patches, resolving bugs, |
| and generally getting ready for the release. |
| |
| 2009-07-16 Allison Randal <allison@perl.org> |
| * Release 3.08 |
| |
| Fix installdirs for Perl versions where Pod::Simple was core; |
| RT#36446 & RT#39709, thanks to Jerry Hedden. |
| |
| Fix encoding handling for code in paragraphs; RT#45829, thanks |
| to David Wheeler. |
| |
| 2008-06-04 Allison Randal <allison@perl.org> |
| * Release 3.07 |
| |
| Fix module dependencies, make HTML::Entities optional and require |
| Test::More. |
| |
| 2008-06-03 Allison Randal <allison@perl.org> |
| * Release 3.06 |
| |
| Fix bugs related to passing $1 to File::Spec, reported by Andrew Hamlin and |
| John McNamara. |
| |
| Applied a suggested fix from Kevin Ryde to return a successful exit |
| code when Pod::Simple::HTML is run from the command line. |
| |
| Fix handling of complex L<URL> entries, thanks to tests supplied in RT#4896. |
| |
| Fix incorrect handling of S<> entries made up of entirely whitespace, thanks |
| to test case from Andreas Koenig. |
| |
| Launch Pod::Simple::XHTML, an XHTML compliant, more easily extensible |
| HTML formatter. |
| |
| Add feature to parse additional text after =begin target as a block |
| title, requested by Adam Kennedy. |
| |
| Thanks to Hans Dieter Pearcey for applying patches, resolving bugs, |
| and generally getting ready for the release. |
| |
| 2007-03-03 Allison Randal <allison@perl.org> |
| * Release 3.05 |
| |
| Standardized all test files on 8.3 naming scheme for Perl core. |
| |
| Applied test patches from Jerry Hedden for Perl core when |
| Encode not installed. |
| |
| Applied test patch from Ken Williams for 5.005_04 compatibility. |
| |
| Applied a patch from Christopher Madsen to fix architecture |
| directory searches on Gentoo. |
| |
| Fixed a failing search test on Debian-based distributions caused |
| by Debian stripping Pod documentation out of core modules. |
| (Three cheers to the CPAN testers and James Ponza for sending |
| enough reports that I could work out the pattern.) |
| |
| 2006-01-18 Allison Randal <allison@perl.org> |
| * Release 3.04 |
| |
| Applied test patches for Perl core integration from Steve Peters. |
| |
| Added a 'reinit' method to Pod::Simple::BlackBox for Russ Allbery |
| so Pod::Man can provide backward compatibility to existing users |
| (such as Module::Build and ExtUtils::MakeMaker). |
| |
| Applied patch for extracting case-preserved package names on VMS |
| from Craig Berry. |
| |
| 2005-11-21 Allison Randal <allison@perl.org> |
| * Release 3.03 |
| |
| Applied whitespace patches for Pod::Man and Pod::Text from |
| Russ Allbery. |
| |
| Applied validation patches to Pod::Simple::HTML from Graham Barr. |
| |
| 2004-05-24 Sean M. Burke <sburke@cpan.org> |
| * Release 3.02 |
| |
| Just fixing some typos in the CSS generated by Pod::Simple:HTMLBatch. |
| |
| 2004-05-24 Sean M. Burke <sburke@cpan.org> |
| * Release 3.01 |
| |
| No big changes to the main modules, but there's many changes to |
| the important Pod::Simple::HTML module. |
| |
| Also, new modules: |
| Pod::Simple::HTMLBatch |
| Pod::Simple::HTMLLegacy |
| Pod::Simple::Progress |
| Pod::Simple::Search |
| and tests for these (well, most). |
| |
| Some prettying up of the Makefile.PL. |
| |
| The test 00about.t is a bit more careful and verbose now. |
| |
| The docs are still incomplete, esp. for Pod::Simple::HTML and |
| Pod::Simple::HTMLBatch, which I hope to improve quite soon. |
| |
| |
| |
| 2004-05-07 Sean M. Burke <sburke@cpan.org> |
| * Release 2.06 |
| |
| Allison Randal brilliantly refactors a huge monolithic sub in |
| Blackbox.pm. Code is now actually sanely readable! |
| |
| I add the new option-attributes fullstop_space_harden and |
| codes_in_verbatim, and the two methods abandon_output_string and |
| abandon_output_fh. Not yet documented. |
| |
| New test fullstop_spaces.t and new corpus document |
| greek_iso_8859_7.pod. |
| |
| Another version should be forthcoming in a few days that has the |
| new Pod::Simple::HTML stuff in it. |
| |
| Note to self: document =extend and =encoding in perlpodspec ASAP! |
| |
| |
| 2003-11-04 Sean M. Burke <sburke@cpan.org> |
| * Release 2.05 -- bugfix version |
| |
| In an attempt to stop Perl 5.6 versions from going completely |
| crazy, I've tried to basically turn off all Unicode/utf8 support |
| under 5.6. Under 5.8 and above, Unicode should work fine, and |
| under 5.6, all Unicode characters should be replaced with a little |
| "can't render" symbol, either a "¤" or a "?". |
| Many many thanks to Jarkko Hietaniemi for helping out. |
| |
| (Works under 5.005 now too?) |
| |
| 2003-10-10 Sean M. Burke <sburke@cpan.org> |
| * Release 2.04 -- minor bugfix version |
| |
| * Added some code to insulate Pod::Simple to runtime changes in |
| the value of $/. Thanks to Iain Truskett for catching this. |
| * Added FILENO method to TiedOutFH.pm, to work quietly under some |
| perls. Thanks to Jochen Stenzel for catching this. |
| * Fixed some tests that erroneously failed under some 5.6's |
| because of chdir()s in *.t files messing up @INC Thanks to many |
| who caught this, including Rocco Caputo. |
| |
| 2003-09-07 Sean M. Burke <sburke@cpan.org> |
| * Release 2.03 -- minor upgrade |
| * A =head[1234] command now closes any currently open =over, and |
| warns. |
| * Fixing a few obscure bugs, including one to do with the |
| Makefile. |
| * Added some tests for those bugs. |
| |
| 2003-09-02 Sean M. Burke <sburke@cpan.org> |
| * Release 2.02 -- fixing a testing bug |
| * Autrijus Tang found a silly bug of mine in corpustest.t's |
| testing of corpus/t/nonesuch.txt. Fixed, |
| * I add encoding_nonesuch.t to test corpus/t/nonesuch.txt better. |
| |
| |
| 2003-09-01 Sean M. Burke <sburke@cpan.org> |
| * Release 2.01 |
| * Moved all version numbers up to 2.01 for reasons of Tibetan |
| numerology. |
| |
| * Implemented =encoding. Thanks a million to Jarkko, Autrijus, |
| Dan Kogai, and many others for their help, patience, and |
| encouragement. |
| |
| It's not yet documented, but see ./t/corpus/*.txt for examples at |
| least. |
| |
| * Added 'use utf8' to all the modules. Byebye perl-5.005 |
| compatibility, hello decent perl-5.6 compatibility. |
| |
| - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
| |
| 2003-09-01 Sean M. Burke <sburke@cpan.org> |
| * Release 0.98 |
| * At Michael Schwern's suggestion, a list that begins with a |
| "=item [number]" line where number isn't a 1, is no longer |
| treated as an error, but instead is silently coerced into being a |
| text-item list, just as if it were "=item wubble" or whatever. |
| |
| 2003-08-12 Sean M. Burke <sburke@cpan.org> |
| * Release 0.97 |
| * Loooking goooooood. Not smelling so much like beta anymore! |
| * I think this might be the last version before I go |
| putting "use utf8" all over the place. |
| |
| * Added placefolders for "=encoding" support. If you use |
| "=encoding", you'll get an error about "not yet implemented" |
| instead of "unknown directive". |
| |
| * Rewrote Pod::Simple::Pullparser's get_title, and added |
| get_version, get_author, and get_description. Documented them. |
| Thanks to Graham Barr for contributing an initial get_title and |
| then being patient while I seemed to do nothing with it for months |
| on end! |
| |
| * More tests. |
| |
| Otherwise just minor changes since last version: |
| * Fixed error in Pod::Simple::RTF. |
| * Added new but undocumented methods to Pod::Simple: |
| unaccept_directive(s) unaccept_target(s) unaccept_code(s) |
| * Corrected '=back without =open' error to '=back without =over' |
| * A little tweaking to the _verbatim_format code. |
| * Dump routines may use \x{NN} instead of \xNN format. |
| * Pod::Simple::HTML now uses VerbatimFormatted |
| * A few changes ot DEBUG messages -- nothing you'd normally see. |
| |
| 2002-11-19 Sean M. Burke <sburke@cpan.org> |
| * Release 0.96 |
| * Still kinda sorta beta. |
| |
| * Much much more docs in this version. Only a few feature |
| changes: |
| |
| * Added any_errata_seen to Pod::Simple. Should've been in there |
| ages ago. Oops! |
| * Fixed some errors in the experimental VerbatimFormatted code. |
| * Added is_tagname / is_tag to Pod::Simple::PullParserStartToken |
| and Pod::Simple::PullParserEndToken |
| * Added RTFDEFLANG stuff to Pod::Simple::RTF. |
| |
| 2002-11-10 Sean M. Burke <sburke@cpan.org> |
| * Release 0.95 |
| * Beta release. Much documentation still to write, many features |
| still to add. The APIs might change in future versions. |
| |
| * Now including perlpod and perlpodspec in the dist. |
| |
| * Pod::Simple -- added parse_from_file |
| * Pod::Simple::RTF -- minor style changes, and minor change to the |
| RTF-wrapping logic. |
| * Pod::Simple::BlackBox -- a =cut opening a block is no longer a |
| fatal(ish) error. |
| * Pod::Simple::BlackBox -- added experimental new |
| VerbatimFormatted stuff. |
| |
| |
| 2002-10-16 Sean M. Burke <sburke@cpan.org> |
| * Release 0.94 |
| * Beta release. Much documentation still to write, many features |
| still to add. The APIs might change in future versions. |
| |
| * Pod::Simple::RTF -- minor style tweaks |
| * Pod::Simple::PullParserEndToken and ::PullParserStartToken -- |
| added ->tag as an alias for ->tagname. |
| * Pod::Simple and Pod::Simple::BlackBox -- added tolerance for |
| "=item * Foo" as a variant syntax for "=item *\n\nFoo". Tests |
| added/changed accordingly. |
| * Pod::Simple::HTML -- added <a name="..."> stuff, and a hack at |
| doing something with X<...>'s. |
| |
| |
| 2002-09-29 Sean M. Burke <sburke@cpan.org> |
| * Release 0.93 |
| * Beta release. Much documentation still to write, many features |
| still to add. The APIs might change in future versions. |
| |
| * Pod::Simple -- added errors_seen attribute |
| * Pod::Simple::HTML -- added support for =for HTML ... directives, |
| and =extend directives. |
| * Oh, and I added Pod::Simple::RTF in 0.92 but forgot to note it |
| until now. |
| |
| 2002-09-29 Sean M. Burke <sburke@cpan.org> |
| * Release 0.92 |
| * Beta release. Much documentation still to write, many features |
| still to add. The APIs might change in future versions. |
| |
| * Fixing bungled distribution. |
| |
| 2002-09-29 Sean M. Burke <sburke@cpan.org> |
| * Release 0.91 |
| * Beta release. Much documentation still to write, many features |
| still to add. The APIs might change in future versions. |
| |
| * Pod::Simple::PullParserTextToken -- added 'text_r' |
| |
| * Pod::Simple::PullParser -- added 'get_title' and |
| 'get_title_short' to |
| |
| * Pod::Simple -- corrected wording of "Format for second =extend |
| parameter" error message. |
| |
| * Pod::PullParser -- made its filter() run as intended, like |
| Pod::Simple's filter. |
| |
| * Pod::Subclassing -- more docs |
| |
| 2002-09-11 Sean M. Burke <sburke@cpan.org> |
| * Release 0.90 |
| * Beta release. Much documentation still to write, many features |
| still to add. The APIs might change in future versions. |