TODO: remove the item about trigger_error, the concern has been addressed
[tweeper.git] / tweeper.1.asciidoc
index 0ffb3b6..8519d3a 100644 (file)
@@ -5,7 +5,7 @@ TWEEPER(1)
 
 NAME
 ----
-tweeper - web scraper to convert a Twitter timeline to an RSS feed
+tweeper - web scraper to convert supported websites (e.g. Twitter.com) to RSS
 
 
 SYNOPSIS
@@ -16,24 +16,27 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-tweeper(1) is a web scraper which extracts the most recent public tweets of
-a given user from their home page on Twitter.com and formats them in RSS, so
-the information can be conveniently accessed and collected by a feed reader.
+tweeper(1) is a web scraper which can be used to conveniently follow the
+public activity of social network users without the need to log in or even be
+subscribed to the social network; tweeper converts the public information to
+RSS so that it can be accessed and collected by a feed reader.
 
-Tweeper started as the TWitter FEEd scraPER but support for other web sites
+tweeper started as the TWitter fEEd scraPER but support for other web sites
 has been added.
 
 The sites that tweeper is able to scrape and convert to RSS are:
-  
+
 * Twitter.com
 * Pump.io based websites, like Identi.ca
 * Dilbert.com
+* Instagram.com
+* Facebook.com (public pages)
 
 tweeper can be used as:
 
 1. a command line tool;
-2. as a filter for feed readers
-3. as a web based tool when PHP support is available in the web server.
+2. a filter for feed readers;
+3. a web based tool when used with a PHP-enabled web server.
 
 
 OPTIONS
@@ -42,6 +45,10 @@ OPTIONS
 *-e*::
     show links to supported media files in the RSS <enclosure/> element
 
+*-u <0|1>*::
+    enable or disable showing usernames in front of the item for hosts which
+    supports it (Twitter.com/Instagram.com). Default is 1 (enable).
+
 *-h, --help*::
     show the help message
 
@@ -51,11 +58,36 @@ EXAMPLE OF USE
 
 Getting the RSS feed of some Twitter user:
 
- tweeper http://twitter.com/NSACareers
+ tweeper https://twitter.com/NSACareers
 
 Using tweeper as a filter for the Liferea feed reader:
 
- liferea-add-feed  "|tweeper http://twitter.com/NSAcareers"
+ liferea-add-feed  "|tweeper https://twitter.com/NSAcareers"
+
+To use tweeper via web there are two options (the examples assume the
+installation directory to be `/usr/share/php/tweeper/`):
+
+1. Using the PHP built-in web server:
+
+  php -S localhost:8000 -t /usr/share/php/tweeper/
++
+and then visit 'http://localhost:8000/tweeper.php' in the web browser.
+
+2. Using a generic web server with the document root in '/var/www':
+
+  sudo ln -s /usr/share/php/tweeper/tweeper.php /var/www
+  xdg-open http://localhost/tweeper.php?src_url=http://twitter.com/NSAcareers
++
+It is enough to create the symlink only the very first time tweeper is used
+this way.
+
+
+NOTES
+-----
+
+In order to use tweeper with a symlink with the apache 'userdir' module, the
+'SymLinksIfOwnerMatch' option must be replaced by 'FollowSymlink' in
+/etc/apache2/mods-enabled/userdir.conf
 
 
 EXIT STATUS
@@ -74,12 +106,12 @@ Antonio Ospite
 
 RESOURCES
 ---------
-Main web site: <http://git.ao2.it/tweeper.git>
+Main web site: <https://git.ao2.it/tweeper.git>
 
 
 COPYING
 -------
-Copyright \(C) 2013  Antonio Ospite <ospite@studenti.unina.it>
+Copyright \(C) 2013-2018  Antonio Ospite <ao2@ao2.it>
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by