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

1 files changed, 63 insertions, 0 deletions

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.