Webmention provides a standard way for one website to inform another that someone, somewhere on the web, has published a reference to a URL under the receiver's domain. This notification travels through very short and simple HTTP POST messages that merely identify the two URLs involved: the source of the mention, and its target. The receiver of a webmention can, at its own leisure, request the HTML document found at the source URL in order to verify the mention, and also to learn more about its author and content via any Microformats2 metadata it may contain. The receiver may then proceed to do something interesting with this fetched and parsed data, such as display hyperlinked information about the mention and its author underneath its own, original content.
For example, a response published on Blog A to an article on Magazine B could result in A sending a webmention to B. (There is implied consent here, since the article on B has a <link> tag in its HTML that explicitly invites webmentions, providing an endpoint URI for them.) It would then become B's responsibility to confirm that the webpage at A really does mention the URL of B's aticle. B may then wish to represent the mention on its own site, however it deems appropriate.
An object of the main Web::Mention class represents a single webmention instance, probably created from an incoming HTTP request, as shown in the synopsis. The object's
verify() method (and, indeed, its
is_verified attribute) will do the hard work of fetching the source URL's document, verifying the presence of the target URL, and parsing any Microformats2 metdata it finds in order to infer author information. The latter goes into a Web::Mention::Author object, and taken all together this should give the receiver enough information to react in some appropriate way to the mention.
This module requires Web::Microformats2, another proposed CPAN module of mine with its own PrePAN page.
Near-future versions of this module will assist with creating and sending webmentions. But receiving is the harder part (and arguably the more rewarding part as well) so I wanted to get it done first. This ended up being a depth-first adventure that resulted in my creating all of Web::Microformats2 before I could come back and finish this module, and so here we are.
I'd like to hear opinions on the name. Giving it a top-level namespace of "Web" seemed natural, for the same arguments I made in Web::Microformats2's case, and then following up the way I did seemed inevitable. But is splitting the word up this way too "cute"? Or, more to the point, will it make it harder to find in CPAN searches?
Certainly "Web::Webmention" is too ugly to live, but I could be talked into e.g. "Net::Webmention" or "HTTP::Webmention" or something. Absent any argument to the contrary, I do like both the directness and the subtle humor of "Web::Mention" the best.
The Web::Microformats2 modules provide Perl programs with a way to parse and analyze HTML documents containing Microformats2 metadata. They can pull Microformats2 information from a given HTML document, representing it as a queryable in-memory object. They can also serialize this object as JSON (using the Microformats2 rules for this), or read an already JSON-serialized Microformats2 structure for further analysis.
CPAN already has HTML::Microformats, Text::Microformat, and Data::Microformat. However, putting aside the fact that the most recent of these was last updated five years ago, they all deal with the original iteration of the Microformats standard. The module I propose, Web::Microformats2, specifically and exclusively addresses Microformats2, a wholly new specification.
Microformats2 is related to its similarly named predecessor in general intent, but its design philosophy and implementation are quite different. As such, software that parses Microformats2 metadata will necessarily be completely separate from that which parses Microformats(1).
Yes, this is a little confusing. I wish it were less so. But that's why my proposed name for this module is "Microformats2": it's simply and literally what the underlying standard calls itself, for good or ill.
My motivation for creating these modules is the IndieWeb movement, which uses Microformats2 as a common standard throughout its many proposals and specifications. I wish to implement certain IndieWeb standards in Perl, and that requires Perl's ability to parse Microformats2 metadata, both as found in HTML documents and as pre-processed JSON.
By filing this modules under the "Web" top-level namespace, I hope to signal their usefulness to the ideal of the open web, specially that as espoused by the IndieWeb movement. In this sense, the specific technologies involved (including HTML and JSON) are less important than the philosophies that hope to bring about a more open web, overall.
And, yes, more practically: were I to name this "HTML::Microformats2", I'm afraid that would imply it to be version 2 of Toby Inkster's HTML::Microformats, which it is not. It serves a wholly distinct purpose from those older modules, and I think it ought to have an appropriately distinct name within the CPAN.