New feature: shareable user query (#6052)

* New feature: shareable user query
Share the output of a user query by RSS / HTML / OPML with other people through unique URLs.
Replaces the global admin token, which was the only option (but unsafe) to share RSS outputs with other people.
Also add a new HTML output for people without an RSS reader.

fix https://github.com/FreshRSS/FreshRSS/issues/3066#issuecomment-648977890
fix https://github.com/FreshRSS/FreshRSS/issues/3178#issuecomment-769435504

* Remove unused method

* Fix token saving

* Implement HTML view

* Update i18n for master token

* Revert i18n get_favorite

* Fix missing i18n for user queries from before this PR

* Remove irrelevant tests

* Add link to RSS version

* Fix getGet

* Fix getState

* Fix getSearch

* Alternative getSearch

* Default getOrder

* Explicit default state

* Fix test

* Add OPML sharing

* Remove many redundant SQL queries from original implementation of user queries

* Fix article tags

* Use default user settings

* Prepare public search

* Fixes

* Allow user search on article tags

* Implement user search

* Revert filter bug

* Revert wrong SQL left outer join change

* Implement checkboxes

* Safe check of OPML

* Fix label

* Remove RSS button to favour new sharing method
That sharing button was using a global admin token

* First version of HTTP 304

* Disallow some recusrivity
fix https://github.com/FreshRSS/FreshRSS/issues/6086

* Draft of nav

* Minor httpConditional

* Add support for offset for pagination

* Fix offset pagination

* Fix explicit order ASC

* Add documentation

* Help links i18n

* Note about deprecated master token

* Typo

* Doc about format

5 files changed, 71 insertions, 26 deletions

diff --git a/docs/en/img/users/user-query-share.png b/docs/en/img/users/user-query-share.png
new file mode 100644
index 000000000..f4cf47991
--- /dev/null
+++ b/docs/en/img/users/user-query-share.png
diff --git a/docs/en/users/03_Main_view.md b/docs/en/users/03_Main_view.md
index 7a0320cb6..6b2cf4313 100644
--- a/docs/en/users/03_Main_view.md
+++ b/docs/en/users/03_Main_view.md
@@ -38,3 +38,4 @@ Reader view will display a feed will all articles already open for reading. Feed
 Read more:
 * [Refreshing the feeds](./09_refreshing_feeds.md)
 * [Filter the feeds and search](./10_filter.md)
+* [User queries](./user_queries.md)
diff --git a/docs/en/users/05_Configuration.md b/docs/en/users/05_Configuration.md
index e2e0f1205..529e3b63f 100644
--- a/docs/en/users/05_Configuration.md
+++ b/docs/en/users/05_Configuration.md
@@ -167,10 +167,7 @@ This means that if you assign a shortcut to more than one action, you’ll end u
 
 # User queries
 
-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.
+You can configure your [user queries](./user_queries.md) in that section.
 
 # Profile
 
diff --git a/docs/en/users/10_filter.md b/docs/en/users/10_filter.md
index 60310c161..519130c14 100644
--- a/docs/en/users/10_filter.md
+++ b/docs/en/users/10_filter.md
@@ -119,34 +119,18 @@ Finally, parentheses may be used to express more complex queries, with basic neg
 
 You can change the sort order by clicking the toggle button available in the header.
 
-## Store your filters
+## Bookmark the current query
 
-Once you came up with your perfect filter, it would be a shame if you need to recreate it every time you need to use it.
+Once you came up with your perfect filter, it would be a shame if you had to recreate it every time you need to use it.
 
-Hopefully, there is a way to bookmark them for later use.
-We call them *user queries*.
+Luckily, there is a way to bookmark them for later use.
+We call them [*user queries*](./user_queries.md).
 You can create as many as you want, the only limit is how they will be displayed on your screen.
 
-### Bookmark the current query
-
-Display the user queries drop-down by clicking the button next to the state buttons.
-![User queries drop-down](../img/users/user.queries.drop-down.empty.png)
-
-Then click on the bookmark action.
-
-Congratulations, you’re done!
-
-### Using a bookmarked query
-
-Display the user queries drop-down by clicking the button next to the state buttons.
-![User queries drop-down](../img/users/user.queries.drop-down.not.empty.png)
-
-Then click on the bookmarked query, the previously stored query will be applied.
-
-> Note that only the query is stored, not the articles.
-> The results you are seeing now could be different from the results on the day you've created the query.
+Read more about [*user queries*](./user_queries.md) to learn how to create them, use them, and even reshare them via HTML / RSS / OPML.
 
 ---
 Read more:
 * [Normal, Global and Reader view](./03_Main_view.md)
 * [Refreshing the feeds](./09_refreshing_feeds.md)
+* [User queries](./user_queries.md)
diff --git a/docs/en/users/user_queries.md b/docs/en/users/user_queries.md
new file mode 100644
index 000000000..68f0898df
--- /dev/null
+++ b/docs/en/users/user_queries.md
@@ -0,0 +1,63 @@
+# User queries
+
+*User queries* are a way to store any FreshRSS search query.
+
+Read about [the filters](./10_filter.md) to learn the different ways to search and filter
+articles in FreshRSS.
+
+## Bookmark the current query
+
+Once you have a search query with a filter, it can be saved.
+
+To do so, display the user queries drop-down menu by clicking the button next to the state buttons:
+
+![User queries drop-down](../img/users/user.queries.drop-down.empty.png)
+
+Then click on the bookmark action.
+
+## Using a bookmarked query
+
+Display the user queries drop-down menu by clicking the button next to the state buttons:
+
+![User queries drop-down](../img/users/user.queries.drop-down.not.empty.png)
+
+Then click on the bookmarked query, the previously stored query will be applied.
+
+> ℹ️ Note that only the search query is stored, not the articles.
+> So the results you are seeing one day might be different another day.
+
+## Share your user queries
+
+A prerequisite is that the FreshRSS API(s) must be enabled in FreshRSS authentication settings.
+
+From the configuration page of the user queries,
+it is possible to share the output of the user queries with external users,
+in the formats HTML, RSS, and OPML:
+
+![Share user query](../img/users/user-query-share.png)
+
+> ℹ️ Note that the sharing as OPML is only available for user queries based on all feeds, a category, or a feed.
+> Sharing by OPML is **not** available for queries based on user labels or favourites or important feeds,
+> to avoid leaking some feed details in an unintended manner.
+
+### Additional parameters for shared user queries
+
+Some parameters can be manually added to the URL:
+
+* `f`: Format of output. Can be `html`, `rss` (`atom` is an alias), or `opml`.
+* `hours`: Show only the articles newer than this number of hours.
+* `nb`: Number of articles to return. Limited by `max_posts_per_rss` in the user configuration. Can be used in combination with `offset` for pagination.
+* `offset`: Skip a number of articles. Used in particular by the HTML view for pagination.
+* `order`: Show the newest articles at the top with `DESC`, or the oldest articles at the top with `ASC`. By default, will use the sort order defined by the user query.
+
+## Sharing with a master token (deprecated)
+
+Before FreshRSS 1.24, the only option to reshare an RSS output was by using a master token,
+like `https://freshrss.example.net/?a=rss&user=alice&token1234`
+
+This was mostly intended for sharing between systems controlled by the same user, and not for sharing publicly.
+
+This method **is not advised anymore** as it is not safe to use the same master token for multiple outputs,
+especially not when shared with other persons.
+
+Now, sharing RSS outputs via user queries is the recommended approach for all scenarios.