Merge pull request #1902 from FreshRSS/dev1.11.0

FreshRSS 1.11.0

8 files changed, 241 insertions, 8 deletions

diff --git a/docs/en/img/users/configuration.article.icons.png b/docs/en/img/users/configuration.article.icons.png
new file mode 100644
index 000000000..d1dd768ad
--- /dev/null
+++ b/docs/en/img/users/configuration.article.icons.png
diff --git a/docs/en/img/users/configuration.navigation.button.png b/docs/en/img/users/configuration.navigation.button.png
new file mode 100644
index 000000000..045956472
--- /dev/null
+++ b/docs/en/img/users/configuration.navigation.button.png
diff --git a/docs/en/img/users/configuration.sharing.png b/docs/en/img/users/configuration.sharing.png
new file mode 100644
index 000000000..a3cfd0570
--- /dev/null
+++ b/docs/en/img/users/configuration.sharing.png
diff --git a/docs/en/users/03_Main_view.md b/docs/en/users/03_Main_view.md
index adb62c7ec..57eab192d 100644
--- a/docs/en/users/03_Main_view.md
+++ b/docs/en/users/03_Main_view.md
@@ -181,3 +181,6 @@ Some operators can be used negatively, to exclude articles, with the same syntax
 `-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.
+
+Combining several search criteria implies a logical *and*, but the keyword ` OR ` can be used to combine several search criteria with a logical *or* instead:
+`author:Dupont OR author:Dupond`
diff --git a/docs/en/users/05_Configuration.md b/docs/en/users/05_Configuration.md
index d0951e905..154cd98b5 100644
--- a/docs/en/users/05_Configuration.md
+++ b/docs/en/users/05_Configuration.md
@@ -3,9 +3,29 @@
 
 ## 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.
+At the moment, FreshRSS is available in 13 languages. After you confirm your choice, the interface will be displayed in the chosen language.
+Depending on the chosen language, there might be parts of the interface that are still not translated. If you're willing to help translating
+the missing bits or add a new language, please check how you can [contribute to the project](../contributing.md#contribute-to-internationalization-i18n).
+
+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 automatic update scripts are part of it.
+
+Not all languages are equals regarding completion:
+
+| Language | Completion |
+|----------|-----------:|
+| cz       | 87.4%      |
+| de       | 88.1%      |
+| en       | 100%       |
+| es       | 88.7%      |
+| fr       | 99.3%      |
+| he       | 69.6%      |
+| it       | 86.4%      |
+| kr       | 96.3%      |
+| nl       | 95.4%      |
+| pt-br    | 87.4%      |
+| ru       | 36.4%      |
+| tr       | 88.1%      |
+| zh-cn    | 99.0%      |
 
 ## Theme
 
@@ -33,7 +53,16 @@ There are some who prefer short lines of text while others prefer to maximize th
 
 ## Article icons
 
-**TODO**
+It worth noting that this section only has effects in normal view.
+
+![Article icons configuration](../img/users/configuration.article.icons.png)
+
+Each article is rendered with a header (top line) and a footer (bottom line).
+In that section, you can choose what will be displayed in those.
+
+If you disable every item in the top line, you'll still be able to see it since
+there is the feed name and the article title. But if you do the same thing for
+the bottom line, it will be empty.
 
 ## HTML5 notification timout
 
@@ -41,6 +70,14 @@ After the automatic updates of the feeds, FreshRSS uses the HTML5 notification A
 
 The duration of this notification can be set. By default, the value is 0.
 
+## Show the navigation button
+
+By default, FreshRSS displays buttons to ease the article navigation when browsing on mobile. The drawback is that they eat up some precious space.
+
+![navigation button configuration](../img/users/configuration.navigation.button.png)
+
+If you don't use those buttons because you never browse on mobile or because you browse with gestures, you can disable them from the interface.
+
 # Reading
 
 **TODO**
@@ -51,15 +88,53 @@ The duration of this notification can be set. By default, the value is 0.
 
 # Sharing
 
-**TODO**
+To make your life easier, you can share directly an article within FreshRSS.
+
+At the moment, FreshRSS supports 15 sharing methods ranging from self-hosted services (Shaarli, etc.) to proprietary services (Facebook, etc.).
+
+By default, the sharing list is empty.
+![Sharing configuration](../img/users/configuration.sharing.png)
+
+To add a new item in the list, follow those simple steps:
+
+ 1. Select the share method in the drop-down.
+ 1. Press the ```✚``` sign to add it to the list.
+ 1. Configure the method in the list. All method names can be modified in the display. Some methods need the sharing URL to be able to work properly (ex: Shaarli).
+ 1. Submit your changes.
+
+To remove an item from the list, follow those simple steps:
+
+ 1. Press the ```❌``` sign next to the share method you want to remove.
+ 1. Submit your changes.
 
 # Shortcuts
 
-**TODO**
+To ease the use of the application, FreshRSS comes with a lot of predefined keyboard shortcuts.
+They allow actions to improve the user experience with a keyboard.
+
+Of course, if you're not satisfied with the key mapping, you can change you configuration to fit your needs.
+
+There are 4 types of shortcuts:
+
+ 1. Views: they allow switching views with ease.
+ 1. Navigation: they allow navigation through articles, feeds, and categories.
+ 1. Article actions: they allow interactions with an article, like sharing or opening it on the original web-site.
+ 1. Other actions: they allow other interactions with the application, like opening the user queries menu or accessing the documentation.
+
+It's worth noting that the share article action has two levels. Once you press the shortcut, a menu containing all the share options opens.
+To choose one share option, you need to select it by its number. When there is only one option, it's selected automatically though.
+
+The same process applies to the user queries.
+
+Be aware that there is no validation on the selected shortcuts.
+This means that if you assign a shortcut to more than one action, you'll end up with some unexpected behavior.
 
 # User queries
 
-**TODO**
+You can configure your [user queries](./03_Main_view.md) in that section. There is not much to say here as it is pretty straightforward.
+You can only change user query titles or drop them.
+
+At the moment, there is no helper to build a user query from here.
 
 # Users
 
diff --git a/docs/en/users/06_Fever_API.md b/docs/en/users/06_Fever_API.md
new file mode 100644
index 000000000..6d8a103b9
--- /dev/null
+++ b/docs/en/users/06_Fever_API.md
@@ -0,0 +1,113 @@
+# FreshRSS - Fever API implementation
+
+See the [page about our Google Reader compatible API](06_Mobile_access.md) for another possibility
+and general aspects of API access.
+
+## RSS clients
+
+There are many RSS clients existing supporting Fever APIs but they seem to understand the Fever API a bit differently.
+If your favourite client does not work properly with this API, create an issue and we will have a look.
+But we can **only** do that for free clients.
+
+### Usage & Authentication
+
+Before you can start to use this API, you have to enable and setup API access, which is [documented here](https://freshrss.github.io/FreshRSS/en/users/06_Mobile_access.html),
+and then re-set the user’s API password.
+
+Then point your mobile application to the URL of `fever.php` (e.g. `https://freshrss.example.net/api/fever.php`).
+
+## Compatibility
+
+Tested with:
+
+- iOS
+  - [Fiery Feeds](https://itunes.apple.com/app/fiery-feeds-rss-reader/id1158763303)
+  - [Unread](https://itunes.apple.com/app/unread-rss-reader/id1252376153)
+
+- MacOS
+  - [Readkit](https://itunes.apple.com/app/readkit/id588726889)
+
+- Android
+  -Until now, we don't know about compatible Android clients. Please leave your feedback, if you tested the Fever API with Android apps.
+  - Please note, that *Press* is NOT compatible: it was a popular RSS client with Fever support, but its development stopped a while ago. It uses the Fever API in a wrong way, which we don't support.
+
+## Features
+
+Following features are implemented:
+
+- fetching categories
+- fetching feeds
+- fetching RSS items (new, favorites, unread, by_id, by_feed, by_category, since)
+- fetching favicons
+- setting read marker for item(s)
+- setting starred marker for item(s)
+- setting read marker for feed
+- setting read marker for category
+- supports FreshRSS extensions, which use th `entry_before_display` hook
+
+Following features are not supported:
+- **Hot Links** aka **hot** as there is nothing in FreshRSS yet that is similar or could be used to simulate it
+
+## Testing and error search
+
+If this API does not work as expected in your RSS reader, you can test it manually with a tool like [Postman](https://www.getpostman.com/).
+
+Configure a POST request to the URL https://freshrss.example.net/api/fever.php?api which should give you the result:
+```json
+{
+	"api_version": 3,
+	"auth": 0
+}
+```
+Great, the base setup seems to work!
+
+Now lets try an authenticated call. Fever uses an `api_key`, which is the MD5 hash of `"$username:$apiPassword"`.
+Assuming the user is `kevin` and the password `freshrss`, here is a command-line example to compute the resulting `api_key`
+
+```sh
+api_key=`echo -n "kevin:freshrss" | md5sum | cut -d' ' -f1`
+```
+
+Add a body to your POST request encoded as `form-data` and one key named `api_key` with the value `your-password-hash`:
+
+```sh
+curl -s -F "api_key=$api_key" 'https://freshrss.example.net/api/fever.php?api'
+```
+
+This shoud give:
+```json
+{
+	"api_version": 3,
+	"auth": 1,
+	"last_refreshed_on_time": "1520013061"
+}
+```
+Perfect, you are authenticated and can now start testing the more advanced features. Therefor change the URL and append the possible API actions to your request parameters. Check the [original Fever documentation](https://feedafever.com/api) for more infos.
+
+Some basic calls are:
+
+- https://freshrss.example.net/api/fever.php?api&items
+- https://freshrss.example.net/api/fever.php?api&feeds
+- https://freshrss.example.net/api/fever.php?api&groups
+- https://freshrss.example.net/api/fever.php?api&unread_item_ids
+- https://freshrss.example.net/api/fever.php?api&saved_item_ids
+- https://freshrss.example.net/api/fever.php?api&items&since_id=some_id
+- https://freshrss.example.net/api/fever.php?api&items&max_id=some_id
+- https://freshrss.example.net/api/fever.php?api&mark=item&as=read&id=some_id
+- https://freshrss.example.net/api/fever.php?api&mark=item&as=unread&id=some_id
+
+Replace `some_id` with a real ID from your `freshrss_username_entry` database.
+
+### Debugging
+
+If nothing helps and your clients still misbehaves, add these lines to the start of `fever.api`:
+
+```php
+file_put_contents(__DIR__ . '/fever.log', $_SERVER['HTTP_USER_AGENT'] . ': ' . json_encode($_REQUEST) . PHP_EOL, FILE_APPEND);
+```
+
+Then use your RSS client to query the API and afterwards check the file `fever.log`.
+
+## Credits
+
+This plugin was inspired by the [tinytinyrss-fever-plugin](https://github.com/dasmurphy/tinytinyrss-fever-plugin).
diff --git a/docs/en/users/06_Mobile_access.md b/docs/en/users/06_Mobile_access.md
index 166985585..c354f98f0 100644
--- a/docs/en/users/06_Mobile_access.md
+++ b/docs/en/users/06_Mobile_access.md
@@ -7,6 +7,9 @@ This page assumes you have completed the [server setup](../admins/02_Installatio
 	* Every user must define an API password.
 	* The reason for an API-specific password is that it may be used in less safe situations than the main password, and does not grant access to as many things.
 
+The rest of this page is about the Google Reader compatible API.
+See the [page about the Fever compatible API](06_Fever_API.md) for another possibility.
+
 
 # Testing
 
@@ -50,3 +53,34 @@ This page assumes you have completed the [server setup](../admins/02_Installatio
 		* [EasyRSS](https://github.com/Alkarex/EasyRSS) (Open source, [F-Droid](https://f-droid.org/packages/org.freshrss.easyrss/))
 	* Linux
 		* [FeedReader 2.0+](https://jangernert.github.io/FeedReader/) (Open source)
+
+
+# Google Reader compatible API
+
+Examples of basic queries:
+
+```sh
+# Initial login, using API password (Email and Passwd can be given either as GET, or POST - better)
+curl 'https://freshrss.example.net/api/greader.php/accounts/ClientLogin?Email=alice&Passwd=Abcdef123456'
+SID=alice/8e6845e089457af25303abc6f53356eb60bdb5f8
+Auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8
+
+# Examples of read-only requests
+curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
+  'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/list?output=json'
+
+curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
+  'https://freshrss.example.net/api/greader.php/reader/api/0/unread-count?output=json'
+
+curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
+  'https://freshrss.example.net/api/greader.php/reader/api/0/tag/list?output=json'
+
+# Retrieve a token for requests making modifications
+curl -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
+  'https://freshrss.example.net/api/greader.php/reader/api/0/token'
+8e6845e089457af25303abc6f53356eb60bdb5f8ZZZZZZZZZZZZZZZZZ
+
+# Get articles, piped to jq for easier JSON reading
+curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
+  'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/reading-list' | jq .
+```
diff --git a/docs/en/users/07_Frequently_Asked_Questions.md b/docs/en/users/07_Frequently_Asked_Questions.md
index 132b2e7ec..42156b1a9 100644
--- a/docs/en/users/07_Frequently_Asked_Questions.md
+++ b/docs/en/users/07_Frequently_Asked_Questions.md
@@ -43,4 +43,12 @@ Since [1.8.0](https://github.com/FreshRSS/FreshRSS/releases/tag/1.8.0) release,
 ```sh
 ./cli/update_user.php --user <username> --password <password>
 ```
-For more information on that matter, there is a [dedicated documentation](../../cli/README.md).
\ No newline at end of file
+For more information on that matter, there is a [dedicated documentation](../../cli/README.md).
+
+## Permissions under SELinux
+
+Some Linux distribution like Fedora or RedHat Enterprise Linux have SELinux system enabled. This acts like a firewall application, so all applications cannot write/modify files under certain conditions. While installing FreshRSS, step 2 can fail if the httpd process cannot write to some data sub-directories, the following command should be executed as root : 
+```sh
+semanage fcontext -a -t httpd_sys_rw_content_t '/usr/share/FreshRSS/data(/.*)?'
+restorecon -Rv /usr/share/FreshRSS/data
+```