Merge pull request #1549 from FreshRSS/dev1.7.0

Version 1.7.0

7 files changed, 522 insertions, 0 deletions

diff --git a/docs/en/users/01_Installation.md b/docs/en/users/01_Installation.md
new file mode 100644
index 000000000..6c979fd42
--- /dev/null
+++ b/docs/en/users/01_Installation.md
@@ -0,0 +1,123 @@
+# Server requirements
+
+FreshRSS is a web application. This means you'll need a web server to run it. FreshRSS requirements are really low, so it could run on most shared host servers.
+
+You need to verify that your server can run FreshRSS before installing it. If your server has the proper requirements and FreshRSS does not work, please contact us to find a solution.
+
+| Software    | Recommended      | Works also with               |
+| ----------- | ---------------- | ----------------------------- |
+| Web server  | **Apache 2**     | Nginx                         |
+| PHP         | **PHP 5.3.7+**   | PHP 5.2+                      |
+| PHP modules | Required: libxml, cURL, PDO_MySQL, PCRE and ctype. \\ Required (32-bit only): GMP \\Recommanded: JSON, Zlib, mbstring, iconv, ZipArchive | |
+| Database    | **MySQL 5.0.3+** | SQLite 3.7.4+                 |
+| Browser     | **Firefox**      | Chrome, Opera, Safari or IE9+ |
+
+## Important notice
+
+FreshRSS **CAN** work with PHP 5.3.3. To do so, we are using specific functions available in the ''password_compat'' library for the form authentication. This library is compatible with PHP >= 5.3.7 but some older version include the patch.
+It all depends on the distribution:
+
+* CentOS and RHEL 6.5 are supported.
+* On the other hand, **Debian with PHP 5.3.3 is not**! ([For more information](https://github.com/ircmaxell/password_compat#requirements))
+
+# Getting the appropriate version of FreshRSS
+
+FreshRSS has three different releases or branches. Each branch has its own release frequency. So it is better if you spend some time to understand the purpose of each release.
+
+## Stable release
+
+[Download](https://github.com/FreshRSS/FreshRSS/archive/master.zip)
+
+This release is done when we consider that our goal concerning the new features and the stability is reached. It could happen that we make two releases in a really short time if we have a really good coding pace. In reality, we are all working on our spare time, so we release every few months. But this version is really stable, tested thoroughly and you should not face any major bugs.
+
+## Development release
+
+[Download](https://github.com/FreshRSS/FreshRSS/archive/dev.zip)
+
+As its name suggests, it is the working release for developers. **This release is unstable!** If you want to keep track of enhancements on a daily basis, you can use it. But keep in mind that you need to follow the branch activity on Github (via [the branch RSS feed](https://github.com/FreshRSS/FreshRSS/commits/dev.atom) for instance). Some say that the main developers use it on a daily basis without problem. They may know what they are doing…
+
+# Apache installation
+
+This is an example Apache virtual hosts configuration file. It covers http and https configuration.
+
+```
+<VirtualHost *:80>
+    ServerName example.com
+    DocumentRoot /path/to/FreshRSS
+
+    ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log
+    CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined
+
+    RewriteEngine on
+    RewriteCond %{SERVER_NAME} = example.com
+    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,QSA,R=permanent]
+</VirtualHost>
+
+<IfModule mod_ssl.c>
+<VirtualHost *:443>
+    ServerName example.com
+    DocumentRoot /path/to/FreshRSS
+
+    ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log
+    CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined
+
+    SSLCertificateFile /path/to/server.crt
+    SSLCertificateKeyFile /path/to/server.key
+
+    # Optional letsencrypt config (uncomment) line below
+    #Include /etc/letsencrypt/options-ssl-apache.conf
+</VirtualHost>
+</IfModule>
+```
+
+# Nginx installation
+
+This is an example nginx configuration file. It covers http, https and php-fpm configuration.
+
+_You can find simpler config file but they may be incompatible with FreshRSS API._
+
+```
+server {
+  listen 80; # http on port 80
+  listen 443 ssl; # https on port 443
+
+  # https configuration
+  ssl on;
+  ssl_certificate      /etc/nginx/server.crt;
+  ssl_certificate_key  /etc/nginx/server.key;
+
+  # your server's url(s)
+  server_name example.com rss.example.com;
+
+  # the folder p of your FreshRSS installation
+  root /srv/FreshRSS/p/;
+
+  index index.php index.html index.htm;
+
+  # nginx log files
+  access_log /var/log/nginx/rss.access.log;
+  error_log /var/log/nginx/rss.error.log;
+
+  # php files handling
+  # this regex is mandatory because of the API
+  location ~ ^.+?\.php(/.*)?$ {
+    fastcgi_pass unix:/var/run/php5-fpm.sock;
+    fastcgi_split_path_info ^(.+\.php)(/.*)$;
+    # By default, the variable PATH_INFO is not set under PHP-FPM
+    # But FreshRSS API greader.php need it. If you have a "Bad Request" error, double check this var !
+    fastcgi_param PATH_INFO $fastcgi_path_info;
+    include fastcgi_params;
+    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
+  }
+
+  location / {
+    try_files $uri $uri/ index.php;
+  }
+}
+```
+
+A step-by-step tutorial is available [in french](http://www.pihomeserver.fr/2013/05/08/raspberry-pi-home-server-installer-un-agregateur-de-flux-rss-pour-remplacer-google-reader/).
+
+# Security
+
+**TODO**
diff --git a/docs/en/users/02_First_steps.md b/docs/en/users/02_First_steps.md
new file mode 100644
index 000000000..96ee264a6
--- /dev/null
+++ b/docs/en/users/02_First_steps.md
@@ -0,0 +1,26 @@
+Learning how to handle a new application is not always easy. We build FreshRSS to be intuitive, but you will need some guidance to get your hand on it.
+
+This section guides you to the pages you need as a new comer.
+
+[After you installed the application](01_Installation.md), the first step is to add one or more feeds. You have few options:
+
+1. [Add a feed manually](04_Subscriptions.md#adding-a-feed)
+2. [Import an OPML or JSON file](04_Subscriptions.md#import-and-export)
+3. [Use the bookmarklet](04_Subscriptions.md#use-bookmarklet)
+4. [Firefox integration](04_Subscriptions.md#firefox-subscription-service)
+
+Once you have added your feeds to FreshRSS, it is time to read them. You have access to three reading modes:
+
+1. [The normal view](03_Main_view.md#normal-view) which allows you to display and read quickly new articles
+2. [The global view](03_Main_view.md#global-view) which allows you to see in one glance the status of your feeds
+3. [The reader view](03_Main_view.md#reader-view) which allows you to have a nice reading experience.
+
+Now that you know the basic usages, it is time to configure FreshRSS to improve your reading experience. It has a lot of options, so play with them to find your perfect configuration. However, here is few resources to help you:
+
+* [Organize your feeds in categories](04_Subscriptions.md#feed-management)
+* [Change the home page](05_Configuration.md#changing-the-view)
+* [Choose the reading options](05_Configuration.md#reading-options)
+* [Refresh feeds](03_Main_view.md#refreshing-feeds)
+* [Filter articles](03_Main_view.md#filtering-articles) for a fast access to a selection
+* [Search an article](03_Main_view.md#searching-articles) published some time ago
+* [Access your feeds on a mobile device](06_Mobile_access.md)
diff --git a/docs/en/users/03_Main_view.md b/docs/en/users/03_Main_view.md
new file mode 100644
index 000000000..53b0beaf2
--- /dev/null
+++ b/docs/en/users/03_Main_view.md
@@ -0,0 +1,183 @@
+# Normal view
+
+**TODO**
+
+# Global view
+
+**TODO**
+
+# Reader view
+
+**TODO**
+
+# Refreshing feeds
+
+To use FreshRSS at its full potential, it needs to grab subscribed feeds new articles. To do so, you have several methods available.
+
+## Automatic update
+
+This is the recommended method since you can forget about it once it is configured.
+
+### With the actualize_script.php script
+
+This method is available only if you have access to the installation server scheduled tasks.
+
+The script is named *actualize_script.php* and is located in the *app* folder. The scheduled task syntax will not be explained here. However, here is [a quick introduction to crontab](http://www.adminschoice.com/crontab-quick-reference/) that might help you.
+
+Here is an example to trigger article update every hour.
+
+```cron
+0 * * * * php /path/to/FreshRSS/app/actualize_script.php > /tmp/FreshRSS.log 2>&1
+```
+
+
+### Online cron
+
+If you do not have access to the installation server scheduled task, you can still automate the update process.
+
+To do so, you need to create a scheduled task, which need to call a specific URL: https://your.server.net/FreshRSS/p/i/?c=feed&a=actualize (it could be different depending on your installation). Depending on your application authentication method, you need to adapt the scheduled task.
+
+#### No authentication
+
+This is the most straightforward since you have a public instance; there is nothing special to configure:
+
+```cron
+0 * * * * curl 'https://your.server.net/FreshRSS/p/i/?c=feed&a=actualize'
+```
+
+### Form or Persona authentication
+
+In those cases, if you configure the application to allow anonymous reading, you can also allow anonymous user to update feeds (“Allow anonymous refresh of the articles”).
+
+![Anonymous access configuration](../img/users/anonymous_access.1.png)
+
+The URL used in the previous section becomes accessible and therefore, you can use the same syntax for the scheduled task.
+
+You can also configure an authentication token to grant a special right on the server.
+
+![Token configuration](../img/users/token.1.png)
+
+The scheduled task syntax to use will be the following:
+
+```cron
+0 * * * * curl 'https://your.server.net/FreshRSS/p/i/?c=feed&a=actualize&token=my-token'
+```
+
+
+### HTTP authentication
+
+In that case, the syntax in the two previous section are unusable. It means that you need to provide your credentials to the scheduled task. **Note that this method is highly discouraged since it means that your credentials will be in plain sight!**
+
+```cron
+0 * * * * curl -u alice:password123 'https://your.server.net/FreshRSS/p/i/?c=feed&a=actualize'
+```
+
+## Manual update
+
+If you cannot or do not want to use the automatic methods, you can make it manually. There is two ways, the partial or the complete update.
+
+### Complete update
+
+This update occurs on all feeds. To trigger it, you need to click on the navigation menu update link.
+
+![Navigation menu](../img/users/refresh.1.png)
+
+When the update starts, a progress bar appears and changes while feeds are processed.
+
+![Progress bar](../img/users/refresh.5.png)
+
+### Partial update
+
+This update occurs on the selected feed only. To trigger it, you need to click on the feed menu update link.
+
+![Feed menu](../img/users/refresh.2.png)
+
+# Filtering articles
+
+While the number of articles stored by FreshRSS increase, it is important to have efficient filters to display only a subset of the articles. There is several methods with different criterion. Most of the time, those methods can be combined.
+
+##By category
+
+It is the easiest method. The only thing to do is clicking on the category title in the side panel. There is two special categories on top of that panel:
+
+  * *Main feed* which displays only articles from feeds marked as available in that category
+  * *Favourites* which displays only articles marked as favourites
+
+##By feed
+
+There is several methods to filter articles by feed:
+
+  * by clicking the feed title in the side panel
+  * by clicking the feed title in the article details
+  * by filtering in the feed options from the side panel
+  * by filtering in the feed configuration
+
+![Feed filter](../img/users/feed.filter.1.png)
+
+##By status
+
+Each article has two attributes, which can be combined. The first attribute indicates if the article was read or not. The second attribute indicates if the article was marked as favorite or not.
+
+With version 0.7, attribute filters are available in the article display dropdown list. With this version, it is not possible to combine those filters. For instance, it is not possible to display only read and favourite articles.
+
+![Attribute filters in 0.7](../img/users/status.filter.0.7.png)
+
+Starting with version 0.8, all attribute filters are visible as toggle icons. They can be combined. As any combination is possible, some have the same result. For instance, the result for all filters selected is the same as no filter selected.
+
+![Attribute filters in 0.8](../img/users/status.filter.0.8.png)
+
+By default, this filter displays only unread articles
+
+##By content
+
+It is possible to filter articles by their content by inputting a string in the search field.
+
+##With the search field
+
+It is possible to use the search field to further refine results:
+
+* by author: `author:name` or `author:'composed name'`
+* by title: `intitle:keyword` or `intitle:'composed keyword'`
+* by URL: `inurl:keyword` or `inurl:'composed keyword'`
+* by tag: `#tag`
+* by free-text: `keyword` or `'composed keyword'`
+* by date of discovery, using the [ISO 8601 time interval format](http://en.wikipedia.org/wiki/ISO_8601#Time_intervals): `date:<date-interval>`
+	* From a specific day, or month, or year:
+		* `date:2014-03-30`
+		* `date:2014-03` or `date:201403`
+		* `date:2014`
+	* From a specific time of a given day:
+		* `date:2014-05-30T13`
+		* `date:2014-05-30T13:30`
+	* Between two given dates:
+		* `date:2014-02/2014-04`
+		* `date:2014-02--2014-04`
+		* `date:2014-02/04`
+		* `date:2014-02-03/05`
+		* `date:2014-02-03T22:00/22:15`
+		* `date:2014-02-03T22:00/15`
+	* After a given date:
+		* `date:2014-03/`
+	* Before a given date:
+		* `date:/2014-03`
+	* For a specific duration after a given date:
+		* `date:2014-03/P1W`
+	* For a specific duration before a given date:
+		* `date:P1W/2014-05-25T23:59:59`
+	* For the past duration before now (the trailing slash is optional):
+		* `date:P1Y/` or `date:P1Y` (past year)
+		* `date:P2M/` (past two months)
+		* `date:P3W/` (past three weeks)
+		* `date:P4D/` (past four days)
+		* `date:PT5H/` (past five hours)
+		* `date:PT30M/` (past thirty minutes)
+		* `date:PT90S/` (past ninety seconds)
+		* `date:P1DT1H/` (past one day and one hour)
+* by date of publication, using the same format: `pubdate:<date-interval>`
+
+Beware that there is no space between the operator and the value.
+
+Some operators can be used negatively, to exclude articles, with the same syntax as above, but prefixed by a `!` or `-`:
+`-author:name`, `-intitle:keyword`, `-inurl:keyword`, `-#tag`, `!keyword`.
+
+It is also possible to combine operators to have a very sharp filter, and it is allowed to have multiple instances of `author:`, `intitle:`, `inurl:`, `#`, and free-text.
diff --git a/docs/en/users/04_Subscriptions.md b/docs/en/users/04_Subscriptions.md
new file mode 100644
index 000000000..0772be4cc
--- /dev/null
+++ b/docs/en/users/04_Subscriptions.md
@@ -0,0 +1,33 @@
+# Adding a feed
+
+**TODO**
+
+# Import and export
+
+**TODO**
+
+# Use bookmarklet
+
+**TODO**
+
+# Feed management
+
+**TODO**
+
+# Firefox subscription service
+
+You can manually add your FreshRSS app to the list of Firefox subscription services which will enable you to subscribe to sites which provide a feed link using the Firefox built-in "Subscribe" button. An in-depth process is described in the [official documentation](https://developer.mozilla.org/en-US/Firefox/Releases/2/Adding_feed_readers_to_Firefox) but you can use the following steps:
+
+  1. Open about:config in Firefox
+
+  2. Search for "browser.contentHandlers.types." and note the highest number following the returned strings (ie if yo see browser.contentHandlers.types.1.something up to browser.contentHandlers.types.5.somethingelse etc. the highest number is 5). Your contentHandler will have to have a free number so just pick one higher than currently registered (you would chose six in above example).
+
+  3. You will have to add three new strings to your about config (replace %NUMBER% with the number from previous step and example.com with your installation address):
+
+  | Preference name                              | Value                                                      | Note                                                      |
+  | -------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------- |
+  | browser.contentHandlers.types.%NUMBER%.title | **FreshRSS**                                               | Use any name you would like (ie. "My feeds")              |
+  | browser.contentHandlers.types.%NUMBER%.type  | **application/vnd.mozilla.maybe.feed**                     | Do not change this value!                                 |
+  | browser.contentHandlers.types.%NUMBER%.uri   | **http://EXAMPLE.COM/FreshRss/i?c=feed&a=add&url_rss=%s** | Replace base url with yours and switch to https (if used) |
+
+  4. Restart Firefox and you can subscribe to sites with the Firefox built-in "Subscribe" button. Just select the name you set under the first Preference name from the dropdown (you can also make it default with the checbox) and you will be redirected to FreshRSS subscription settings (you must be logged in).
diff --git a/docs/en/users/05_Configuration.md b/docs/en/users/05_Configuration.md
new file mode 100644
index 000000000..f8ac56cd7
--- /dev/null
+++ b/docs/en/users/05_Configuration.md
@@ -0,0 +1,121 @@
+
+# Display
+
+## Language
+
+At the moment, FreshRSS is available in French and English. After you confirm your choice, the whole interface will be displayed in the chosen language.
+
+There are parts of FreshRSS that are not translated and are not intended to be translated. For now, the logs visible in the application as well as the one generated by the script of automatic update are part of it.
+
+## Theme
+
+In matters of taste and color, there can be no disputes. This is why FreshRSS offers six official themes:
+
+ * *Blue Lagoon* by **Mister aiR**
+ * *Dark* by **AD**
+ * *Flat design* by **Marien Fressinaud**
+ * *Origine* by **Marien Fressinaud**
+ * *Pafat* by **Plopoyop**
+ * *Screwdriver* by **Mister aiR**
+
+If none of these are suitable for you, it is always possible to create your own.
+
+To select a theme, simply scroll through the themes and select a theme that appears. After confirmation, the theme will be applied to the interface.
+
+## Content width
+
+There are some who prefer short lines of text while others prefer to maximize the available screen space. To satisfy the maximum number of people it is possible to choose the width of the displayed content. There are four settings available:
+
+ * **Fine** which displays content up to 550 pixels
+ * **Medium** which displays content up to 800 pixels
+ * **Large** which displays content up to 1000 pixels
+ * **No limit** which displays the content on 100% of the available space
+
+## Article icons
+
+**TODO**
+
+## HTML5 notification timout
+
+After the automatic updates of the feeds, FreshRSS uses the HTML5 notification API to notify of the arrival of new articles.
+
+The duration of this notification can be set. By default, the value is 0.
+
+# Reading
+
+**TODO**
+
+# Archiving
+
+**TODO**
+
+# Sharing
+
+**TODO**
+
+# Shortcuts
+
+**TODO**
+
+# User queries
+
+**TODO**
+
+# Users
+
+**TODO**
+
+## Authentication methods
+
+### HTTP Authentication (Apache)
+
+ 1. User control is based on the .htaccess file
+ 2. It is best practice to place the .htaccess file in ./i/ subdirecotry so API and other third party services can work.
+ 3. If you want to limit all access to registered users only, place the file in the directory of FreshRSS or in a parent directory. Note that PubsubHubbub and API will not work!
+ 4. Example .htaccess file for a user "marie":
+
+```
+AuthUserFile /home/marie/repertoire/.htpasswd
+AuthGroupFile /dev/null
+AuthName "Chez Marie"
+AuthType Basic
+Require user marie
+```
+
+More information can be found in [Apache documentation](http://httpd.apache.org/docs/trunk/howto/auth.html#gettingitworking).
+
+# Subscription management
+
+## Information
+
+**TODO**
+
+## Archivage
+
+**TODO**
+
+## Login
+
+**TODO**
+
+## Advanced
+
+### Retrieve a truncated stream
+
+The question comes up regularly, so we will try to clarify here how one can retrieve a truncated RSS feed with FreshRSS. Please note that the process is absolutely not "user friendly", but it works :)
+
+Also know that this way you are generating much more traffic to the originating sites and that they can block you accordingly. The performance of FreshRSS is also imapcted because you have to fetch the contents of the articles one by one. So it's a feature to use sparingly!
+
+What is meant by "CSS path of articles on the original site" actually corresponds to the "path" consisting of IDs and classes (which in html, matches the id and class attributes) to retrieve only the interesting part that corresponds to the article. Ideally, this path starts with an id (which is unique to the page).
+
+#### Example 1: Rue89
+
+To find this path, you must go to the address of one of the truncated articles (for example http://www.rue89.com/2013/10/15/prof-maths-jai-atteint-lextase-dihn-pedagogie-inversee-246635). You must then look for the "block" of HTML corresponding to the content of the article (in the source code!).
+
+We find here that the block that encompasses only the content of the article is ```<div class="content clearfix">```. We will only use the ".content" class here. Nevertheless, as said above, it is best to start the path with an id. If we go back to the parent block, this is the block ```<div id="article">``` and that's perfect! The path will be ```#article .content```.
+
+#### Add the corresponding classes to the articles CSS path on the feed configuration page. Examples:
+
+*  Rue89: ```#article .content```
+*  PCINpact: ```#actu_content```
+*  Lesnumériques: ```article#body div.text.clearfix```
\ No newline at end of file
diff --git a/docs/en/users/06_Mobile_access.md b/docs/en/users/06_Mobile_access.md
new file mode 100644
index 000000000..e1a23c8ba
--- /dev/null
+++ b/docs/en/users/06_Mobile_access.md
@@ -0,0 +1 @@
+**TODO**
diff --git a/docs/en/users/07_Frequently_Asked_Questions.md b/docs/en/users/07_Frequently_Asked_Questions.md
new file mode 100644
index 000000000..6391c55f5
--- /dev/null
+++ b/docs/en/users/07_Frequently_Asked_Questions.md
@@ -0,0 +1,35 @@
+We may not have answered all of your questions in the previous sections. The FAQ contains some questions that have not been answered elsewhere.
+
+## What is /i at the end of the application URL?
+
+Of course, ```/i``` has a purpose! We used it for performance and usability:
+
+* it allows to serve icons, images, styles and scripts without cookies. Whitout that trick, those files will be downloaded more often, specially when the form or the Personna authentications are used. Also, HTTP requests will be heavier.
+* ```./p/``` public root can be served without any HTTP access restrictions. Whereas it could be implemented in ```./p/i/```.
+* It spares from having problems while serving public resources like ```favicon.ico```, ```robots.txt```, etc.
+* It allows to display the logo instead of a white page while hitting a restriction or a delay during the loading process.
+
+## Why robots.txt is located in a sub-folder?
+
+To increase security, FreshRSS is hosted in two sections. The first section is public (```./p``` folder) and the second section is private (everything else). Therefore the ```robots.txt``` file is located in ```./p``` sub-folder.
+
+As explained in the [security section](/en/User_documentation/Installation/Security), it is highly recommended to make only the public section available at the domain level. With that configuration, ```./p``` is the root folder for http://demo.freshrss.org/, thus making ```robots.txt``` available at the root of the application.
+
+The same rule applies for ```favicon.ico``` and ```.htaccess```.
+
+## Why do I have errors while registering a feed?
+
+There can be different origins for that problem.
+The feed syntax can be invalid, it can be unrecognized by the SimplePie library. the hosting server can be the root of the problem, FreshRSS can be buggy.
+The first step is to identify what causes the problem.
+Here are the steps to follow:
+
+1. __Verify if the feed syntax is valid__ with the [W3C on-line tool](http://validator.w3.org/feed/ "RSS and Atom feed validator"). If it is not valid, there is nothing we can do.
+1. __Verify SimplePie validation__ with the [SimplePie on-line tool](http://simplepie.org/demo/ "SimplePie official demo"). If it is not recognized, there is nothing we can do.
+1. __Verify FreshRSS integration__ with the [demo](http://demo.freshrss.org "FreshRSS official demo"). If it is not working, you need to [create an issue on Github](https://github.com/FreshRSS/FreshRSS/issues/new "Create an issue for FreshRSS") so we can have a look at it. If it is working, there is probably something fishy with the hosting server.
+
+Here is a list of feed which don't work:
+
+* http://foulab.org/fr/rss/Foulab_News: is not a W3C valid feed (November 2014)
+* http://eu.battle.net/hearthstone/fr/feed/news: is not a W3C valid feed (Novembre 2014)
+* http://webseriesmag.blogs.liberation.fr/we/atom.xml: is not working for the user but succeed on all the described validations (November 2014)
\ No newline at end of file