tweeper.php: support host-specific methods for preprocessing the HTML data

Some sites serve mangled HTML code, so a mechanism to clean it up before
loading it as XML is needed.

For instance, facebook.com puts come content inside HTML comments, and
these must be stripped in order to make the content available to the
HTML parser when loading the data into a DOMDocument.

tweeper.php: strip the leading "www." from hosts

This makes tweeper more forgiving when it is passed URLs either with or
without the "www" subdomain for the same host.

tweeper.php: make error about missing stylesheet more explicit

rss_converter_instagram.com.xsl: update to new json format

The new Instagram homepage provides json data in a format different than
before, update the xsl to support it.

Unfortunately the data in the new format does not provide the
descriptions of the items, so use some placeholder values (URL, comments
count, likes count) to present at least something.

rss_converter_twitter.com.xsl: update XPath of tweet content

Using the role attribute to differentiate between original tweets and
quoted tweet, as introduced in commit 4c2e986, does not work anymore,
but the fact that original tweets are <li></li> elements while quoted
tweets are <div></div> elements can be used instead.

rss_converter_twitter.com.xsl: improve matching the permalink

Extract the permalink using the @data-permalink-path attribute, this
works for withheld tweets too preventing them from having all the same
guid.

rss_converter_twitter.com.xsl: restrict tweet matching

With new style retweets the quoted text is also matched by
[@data-item-type='tweet'] but then the content is not handled, resulting
in empty items in the RSS feed.

Checking also for @role='listitem' allows to pick up only top-level
tweets.

tweeper.php: make date handling functions a little more robust

Provide at least _some_ error checking and a fall-back value for invalid
dates.

tweeper.php: factor out an is_cli() function

README: mention the supported sites in the README file

tweeper.1.asciidoc: mention the supported sites in the man page

TODO: update some entries

The new Dilbert.com site does not have a different /fast version, so no
point in mentioning it.

Mention possible support for Instagram videos.

Add support for converting Instagram user timelines to RSS

tweeper.php: add infrastructure for sites using json data

Some websites provide the timelines as json data and convert that to
html in the client.

Supporting these sites will be done by defining host specific methods to
extract the json data to pass to json_to_xml().

tweeper.php: fix validation when generating enclosure elements

The RSS specification says that the enclosure element url must be http.
See http://sourceforge.net/p/feedvalidator/bugs/72/

So follow the specification, for now. If feedvalidator decides to relax
this requirement this hack will be removed.

tweeper.php: factor out an html_to_xml() function from the tweep() method

Split the operation to get some xml out of the web page, this in
preparation for adding some more flexibility about what can be converted
to xml for a subsequent transformation.

tweeper.php: move loading the stylesheet into the Tweeper class

Let the Tweeper class load the stylesheet, specifically when the tweep()
method is called.

This way the same Tweeper object can be reused to convert different URLs
from different websites.

rss_converter_twitter.com.xsl: use ProfileHeaderCard as channel description

Strip trailing newlines

rss_converter_pump.io.xsl: make the feed validate with feedvalidator.org

Make the pump.io feed validate with http://feedvalidator.org and also
improve compatibility by providing a guid and by excluding the weird
xmlns:php namespace in the output.

rss_converter_dilbert.com.xsl: make the feed validate with feedvalidator.org

Make the Dilbert.com feed validate with http://feedvalidator.org and also
improve compatibility by providing a guid and by excluding the weird
xmlns:php namespace in the output.

rss_converter_dilbert.com.xsl: fixes for the new dilbert.com

Make the stylesheet work again with the new dilbert.com website.

rss_converter_howtoons.com.xsl: make the feed validate with feedvalidator.org

Make the Howtoons.com feed validate with http://feedvalidator.org and
also improve compatibility by providing a guid and by excluding the
weird xmlns:php namespace in the output.

rss_converter_twitter.com.xsl: improve the naming of some variables

Use item-content and item-permalink instead of tweet-text and
tweet-link, this way other stylesheets can use the same names resulting
in more consistency.

rss_converter_twitter.com.xsl: rename twitterBaseURL to BaseURL

This way the same notation is used in all the stylesheets.

rss_converter_twitter.com.xsl: make the feed validate with feedvalidator.org

Make the Twitter feed validate with http://feedvalidator.org and also
improve compatibility by providing a guid and by excluding the weird
xmlns:php namespace in the output.

NEWS: add release notes for the v0.3 release

Update email address and copyright years

Add a stylesheet for Howtoons.com

rss_converter_twitter.com.xsl: fix getting the profile picture

Some more values are added tot he class attribute so the old equality
check does not work anymore.

Use a contains() check, this is more future proof and allows also to
support both the classic and the new profile pages.

rss_converter_twitter.com.xsl: support the new Twitter profile page

Adjust the XPath expressions to support both the classic and the new
profile pages.

rss_converter_*.xsl: specify xml:base

Some feed readers expand relative URLs in items by extracting the base
URL from the enclosing <link/> element, however this is not a globally
accepted practice.

Specifying xml:base is useful to cover other ways in which relative URLs
are expanded, see:
  https://cyber.law.harvard.edu/rss/relativeURI.html
  http://www.w3.org/TR/xmlbase/#resolution

tweeper.php: support generating enclosure for "audio/ogg"

tweeper.1.asciidoc: reword some list items

Remove the unneeded "as", it is in the list preamble already.

Remove the auto-generated ChangeLog

It is not that useful once we have a nice NEWS file; and the latter can
even be used as upstream changelog in packages.

tweeper.1.asciidoc: mention a way to use tweeper from a web server

Makefile: fix typo s/INTALLATION/INSTALLATION/

Thanks-to: gregor herrmann <gregoa@debian.org>

Changelog, NEWS: prepare for the v0.2 release

tweeper.1.asciidoc: small fixes to the man page

tweeper.1.asciidoc: add a missing semicolon

Add a ChangeLog file

Add a NEWS file

Add a Makefile rule to generate a Changelog file

Add a man page

Add a Makefile to simplify installation and packaging

Add a wrapper script intended to be called as an executable

Add also an INSTALL file which explains how to set up tweeper globally
on the filesystem.

Write error messages on STDERR and return saner values in CLI mode

The previous use of die() was not very useful in CLI mode as the script
was always returning 0.

Fix that and also write error messages to the appropriate output stream.

Note the use of 'php://output' as error stream for non CLI mode, this
ensures that error messages would be readable in the browser window.

TODO: add more info about checking UTF output

Handle errors and warnings from loadHTML()

When parsing invalid documents loadHTML() spits out warnings and errors
which may end up polluting the output of tweeper depending on the value
of the "display_errors" variable in the PHP configuration; this may
result in the output being invalid RSS.

Handling those messages explicitly makes tweeper more robust against
different PHP configurations.

Thanks-to: gregor herrmann <gregoa@debian.org>

Show the actual name of the user the tweet comes from

The old way of using just the screen name made re-tweeted messages look
like they were coming from the re-twitting user instead of the original
author. This is wrong and causes confusion, fix it.

Follow HTTP redirects in get_contents() too

This is especially needed when http:// URLs are redirected to https://

Add some entries to the TODO file

Merge branch 'generate-enclosure-element'

Cosmetics: re-indent cURL options to follow the coding style

Use cURL for Tweeper::get_contents() too

So that the same mechanism is used for getting content and info.

Note, the "file://" scheme has to be prepended to local files so cURL
can handle them.

Remove double semicolon in Tweeper::get_info()

Make get_url_info() and generate_enclosure() static methods

Also rename get_url_info() to get_info() to match the naming scheme of
get_contents().

Turn epoch_to_gmdate() and str_to_gmdate() into static methods

Make get_contents() a static method

Cosmetics: sort supported_content_types, remove unneeded spaces

Use an array to list supported content types for enclosures

Make it optional to generate the <enclosure/> element

Use getopt() to parse command line options

This will make it easier to add more options.

Split parsing CLI options from parsing QUERY_STRING ones

This will make it easier to add more options.

Use templates to generate enclosures

This has two benefits:
  - make it possible to handle multiple enclosures;
  - handle _only_ the anchors with the 'data-expanded-url' attribute,
    before the change every anchor with the 'twitter-timeline-link'
    attribute was handled.

The change also makes the DOM navigation a little lighter because now
only $tweet-text is searched for the 'data-expanded-url' attribute.

Merge https://github.com/grote/Tweeper into generate-encolure-elements

Fix a typo: s/tweeter/Twitter/

only enclosify certain mimetypes, use same user agent

add initial support for enclosures

Fix a typo in an error message

Add an RSS conversion stylesheet for dilbert.com

Since June 18, 2013 dilbert.com strips are not accessible anymore
directly from the RSS feed, this message is displayed instead:

  Dilbert readers - Please visit Dilbert.com to read this feature. Due
  to changes with our feeds, we are now making this RSS feed a link to
  Dilbert.com.

How unhandy is that, was it because of a management decision?
Maybe a parody dilbert strip is needed about this issue...

TODO: mention the <ttl/> RSS element

rss_converter_twitter.com.xsl: use concat() more

I think it is a little more readable, and it surely takes less
characters.

Add an example with identi.ca

Mention in the README that other sites can be converted to RSS

Add initial support for scraping Pump.io activity streams

Use symlinks to represent alternate sites with the same structure (i.e.
same server software).

Symlinks are handy and concise, an alternative way would be to introduce
some equivalence mapping, like in the patch below, but I don't really
like that:

  diff --git a/tweeper.php b/tweeper.php
  index a019684..eb12af2 100755
  --- a/tweeper.php
  +++ b/tweeper.php
  @@ -101,9 +101,18 @@ $url = parse_url($src_url);
   if (FALSE === $url || empty($url["host"]))
     die("Invalid url: $url\n");

  -$stylesheet = __DIR__ . "/rss_converter_" . $url["host"] . ".xsl";
  +$equivalence_map = array(
  +  "identi.ca" => "pump.io"
  +);
  +
  +if (array_key_exists($url["host"], $equivalence_map))
  +  $host = $equivalence_map[$url["host"]];
  +else
  +  $host = $url["host"];
  +
  +$stylesheet = __DIR__ . "/rss_converter_" . $host . ".xsl";
   if (FALSE === file_exists($stylesheet))
  -  die("Conversion to RSS not supported: {$url["host"]}\n");
  +  die("Conversion to RSS not supported: {$host}\n");

   $tweeper = new Tweeper($stylesheet);
   echo $tweeper->tweep($src_url);

Change mode of tweeper.php

It is not going to be executed directly anyways.

Add -h and --help options

Add another date conversion routine

Update the documentation to use URLs as arguments

This change of behaviour of the interface makes the implementation of
multi-site support a lot easier.

Mention rssitfor.me as an alternative service

Use __DIR__ when building the stylesheet path name

This makes it possible to call tweeper.php with an absolute path.

For now the stylesheet are assumed to be in the same directory of the
program; I have no experience with distributing php software for command
line usage, so I don't know yet how to properly handle include paths.

Rename formatDate() function to epoch_to_gmdate()

The could be different date conversion functions in the future.

Be more verbose in error messages

Make stylesheet file name parametric

The host is encoded in the file name, this is in order to support more
sites with no changes to the code, all that is needed is just new
stylesheets with the host in their filename following the scheme will:

  rss_converter_HOST.xsl

Where HOST has the meaning of the "host" field in the return value of
the PHP parse_url() function.

Change of behavior| Now a URL is required as an argument

This makes the program more generic and prepares it to support feed
scraping for more websites.

Factor out a usage() function

Use php_sapi_name() to check for CLI interface

Fix a typo

Add more info about how to call Tweeper from command line

Embed the full HTML content of the tweet in the description field

Use CDATA to embed the exact copy of an element; it is neat and we get
click-able links in the feed reader for free.

Format dates using an external php function

Initial import