FreshRSS/rssguard
1
0
Fork 0
mirror of https://github.com/martinrotter/rssguard.git synced 2025-01-27 07:46:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Docs update

Browse Source
This commit is contained in:
Martin Rotter 2022-02-16 11:01:10 +01:00
parent fd7b407de4
commit ddb805438f
4 changed files with 41 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
resources/desktop/com.github.rssguard.appdata.xml
View File

@ -26,7 +26,7 @@
<url type="donation">https://github.com/sponsors/martinrotter</url>
<content_rating type="oars-1.1" />
<releases>
<release version="4.1.2" date="2022-02-15"/>
<release version="4.1.2" date="2022-02-16"/>
</releases>
<content_rating type="oars-1.0">
<content_attribute id="violence-cartoon">none</content_attribute>

67
resources/docs/Documentation.md
View File

@ -1,6 +1,7 @@
# 🔥 RSS Guard Documentation 🔥
Welcome to RSS Guard documentation. You can find everything about the application right here. \
Welcome to RSS Guard documentation. You can find everything about the application right here.
There is a [Discord server](https://discord.gg/7xbVMPPNqH) for user communication.
## Table of Contents
@ -32,13 +33,13 @@ There is a [Discord server](https://discord.gg/7xbVMPPNqH) for user communicatio
<hr style="margin: 40px;"/>
## What is RSS Guard? <a id="wirss" />
RSS Guard is an [open-source](https://en.wikipedia.org/wiki/Open_source) [cross-platform](#sos) [multi-protocol](#sfr) desktop feed reader. It is able to fetch almost any of the known feed formats, including RSS/RDF/ATOM/JSON. RSS Guard is developed on top of the [Qt library](http://qt-project.org).
## What is RSS Guard? <a id="wirss"></a>
RSS Guard is an [open-source](https://en.wikipedia.org/wiki/Open_source) [cross-platform](#sos) [multi-protocol](#sfr) desktop feed reader. It is able to fetch feeds in RSS/RDF/ATOM/JSON formats. RSS Guard is developed on top of the [Qt library](http://qt-project.org).
## Downloads <a id="dwn"></a>
Official place to download RSS Guard is at [Github Releases](https://github.com/martinrotter/rssguard/releases). You can also download the [development (beta) build](https://github.com/martinrotter/rssguard/releases/tag/devbuild), which is updated automatically every time the source code is updated.
Also, RSS Guard is available for [many Linux distributions](https://repology.org/project/rssguard/versions), and even via [Flathub](https://flathub.org/apps/details/com.github.rssguard).
RSS Guard is also available for [many Linux distributions](https://repology.org/project/rssguard/versions), and even via [Flathub](https://flathub.org/apps/details/com.github.rssguard).
I highly recommend to download RSS Guard only from reputable sources.
@ -53,11 +54,11 @@ RSS Guard is a cross-platform application, and at this point it is known to work
## Major Features <a id="mfe"></a>
### Supported Feed Readers <a id="sfr"></a>
RSS Guard is a multi-account application and supports many web-based feed readers via [built-in plugins](#papi). One of the plugins, of course, provides the support for standard **RSS/ATOM/JSON** feeds with the set of features everyone would expect from classic feed reader, like OPML support, etc.
RSS Guard is multi-account application and supports many web-based feed readers via [built-in plugins](#papi). One of the plugins, of course, provides the support for standard **RSS/ATOM/JSON** feeds with the set of features everyone would expect from classic feed reader, like OPML support, etc.
I organized the supported web-based feed readers into an elegant table:
| Service | Two-way Synchronization | [Intelligent Synchronization Algorithm](#intel) (ISA) <sup>1</sup> | Synchronized Labels <sup>2</sup> <a id="sfrl"></a> | OAuth |
| Service | Two-way Synchronization | [Intelligent Synchronization Algorithm](#intel) (ISA) <sup>1</sup> | Synchronized Labels <sup>2</sup> <a id="sfrl"></a> | OAuth <sup>4</sup> |
| :--- | :---: | :---: | :---: | :---:
| Feedly | ✅ | ❌ | ✅ | ✅ (only for official binaries)
| Gmail | ✅ | ❌ | ❌ | ✅
@ -80,38 +81,40 @@ With ISA, RSS Guard only downloads articles which are new or were updated. While
* TheOldReader
* FreshRSS
<sup>4</sup> [OAuth](https://en.wikipedia.org/wiki/OAuth) is secure way of authenticating users in online applications.
### Article Filtering <a id="fltr"></a>
Sometimes you need to tweak incoming article - mark them starred, remove ads from their contents or simply ignore them. That's where filtering feature comes in.
Sometimes you need to tweak incoming article - mark it starred, remove ads from its contents or simply ignore it. That's where filtering feature comes in.
<img alt="alt-img" src="images/filters-dialog.png" width="600px">
#### Writing article filter
Article filters are fully scriptable and consist of arbitrary JavaScript code which must provide function with prototype:
Article filters are small JavaScript pieces of code which must provide function with prototype:
```js
function filterMessage() { }
```
The function should be fast enough, and must return values which belong to enumeration [`FilteringAction`](#FilteringAction-enum). You can either use direct numerical value of each enumerant, for example `2`, or you can use self-descriptive name, for example `MessageObject.Ignore`. There are also names `MSG_ACCEPT` and `MSG_IGNORE` as aliases for `MessageObject.Accept` and `MessageObject.Ignore`.
The function should be fast enough and must return values which belong to enumeration [`FilteringAction`](#FilteringAction-enum).
Each message/article is accessible in your script via global variable named `msg` of type `MessageObject`, see [this file](https://github.com/martinrotter/rssguard/blob/master/src/librssguard/core/messageobject.h) for the declaration. Some properties are writeable, allowing you to change contents of the message before it is written to DB. You can mark message important, parse its description, perhaps change author name or even assign some label to it!!!
Each article is accessible in your script via global variable named `msg` of type `MessageObject`, see [this file](https://github.com/martinrotter/rssguard/blob/master/src/librssguard/core/messageobject.h) for the declaration. Some properties are writeable, allowing you to change contents of the article before it is written to RSS Guard's DB. You can mark article important, change its description, perhaps change author name or even assign some label to it!!!
You can use [special placeholders](#userd-plac) within article filter.
Also, there is a special variable named `utils`. This variable is of type `FilterUtils` and offers some useful [utility functions](#utils-object) for you to use in your filters.
RSS Guard also allows to use the list of labels assigned to each message. You can, therefore, execute actions in your filtering script, based on which labels are assigned to the message. The property is called `assignedLabels` and is array of [`Label`](#Label-class) objects. If you change assigned labels to the message, then the change will be eventually [synchronized](#sfrl) back to server if respective plugin supports it.
RSS Guard allows to use the list of labels assigned to each article. You can, therefore, execute actions in your filtering script, based on which labels are assigned to the article. The property is called `assignedLabels` and is array of [`Label`](#Label-class) objects. If you change labels assigned to some article, then the change will be eventually [synchronized](#sfrl) back to server if respective plugin/service supports it.
Passed message also offers special function:
Passed article also offers special function:
```js
Boolean MessageObject.isDuplicateWithAttribute(DuplicationAttributeCheck)
Boolean MessageObject.isAlreadyInDatabase(DuplicationAttributeCheck)
```
Which allows you to perform runtime check for existence of the message in RSS Guard's database. The parameter is integer value from enumeration [`DuplicationAttributeCheck`](#DuplicationAttributeCheck-enum) and specifies how exactly you want to determine if given message is "duplicate". Again, you can use direct integer values or enumerant names.
which allows you to perform runtime check for existence of the article in RSS Guard's database. The parameter is value from enumeration [`DuplicationAttributeCheck`](#DuplicationAttributeCheck-enum) and specifies how exactly you want to match your article.
For example, if you want to check if there is already another message with same author in database, you should call `msg.isDuplicateWithAttribute(MessageObject.SameAuthor)`. Values of the enumeration can be combined via bitwise `|` operation in single call, for example like this: `msg.isDuplicateWithAttribute(MessageObject.SameAuthor | MessageObject.SameUrl)`.
For example, if you want to check if there is already another message with same author in database, you should call `msg.isAlreadyInDatabase(MessageObject.SameAuthor)`. Values of the enumeration can be combined via bitwise OR (`|`) operator in single call, like this: `msg.isAlreadyInDatabase(MessageObject.SameAuthor | MessageObject.SameUrl)`.
Here is the reference of methods and properties of some types available in your filtering scripts.
Here is the reference of methods and properties of types available in your filtering scripts.
#### `MessageObject` class
| Type | Name(Parameter) | Return value | Read-only | Description
@ -121,18 +124,18 @@ Here is the reference of methods and properties of some types available in your
| Property | `feedCustomId` | `String` | ✅ | Service-specific ID of the feed which this message belongs to.
| Property | `accountId` | `Number` | ✅ | RSS Guard's ID of the account activated in the program. This property is highly advanced and you probably do not need to use it at all.
| Property | `id` | `Number` | ✅ | ID assigned to the message in RSS Guard local database.
| Property | `customId` | `String` | ✅ | ID of the message as provided by the remote service.
| Property | `customId` | `String` | ✅ | ID of the message as provided by the remote service or feed file.
| Property | `title` | `String` | | Title of the message.
| Property | `url` | `String` | | URL of the message.
| Property | `author` | `String` | | Author of the message.
| Property | `contents` | `String` | | Contents of the message.
| Property | `rawContents` | `String` | | This is RAW contents of the message as it was obtained from remote service/feed. You can expect raw `XML` or `JSON` element data here. Note that this attribute has some value only if `runningFilterWhenFetching` returns `true`. In other words, this attribute is not persistently stored inside RSS Guard's DB. Also, this attribute is artificially filled with ATOM-like data when testing the filter.
| Property | `score` | `Number` | | Arbitrary number in range \<0.0, 100.0\>. You can use this number to sort messages in a custom fashion as this attribute also has its own column in messages list.
| Property | `score` | `Number` | | Arbitrary number in range \<0.0, 100.0\>. You can use this number to sort messages in a custom fashion as this attribute also has its own column in articles list.
| Property | `created` | `Date` | | Date/time of the message.
| Property | `isRead` | `Boolean` | | Is message read?
| Property | `isImportant` | `Boolean` | | Is message important?
| Property | `isDeleted` | `Boolean` | | Is message placed in recycle bin?
| Method | `isDuplicate(DuplicationAttributeCheck)` | `Boolean` | | Allows you to test if this particular message is already stored in RSS Guard's DB.
| Method | `isAlreadyInDatabase(DuplicationAttributeCheck)` | `Boolean` | | Allows you to test if this particular message is already stored in RSS Guard's DB.
| Method | `assignLabel(String)` | `Boolean` | | Assigns label to this message. The passed `String` value is the `customId` property of `Label` type. See its API reference for relevant info.
| Method | `deassignLabel(String)` | `Boolean` | | Removes label from this message. The passed `String` value is the `customId` property of `Label` type. See its API reference for relevant info.
| Property | `runningFilterWhenFetching` | `Boolean` | ✅ | Returns `true` if current run of the message filter is done when message is fetched. Returns `false` if message filter runs manually, for example from `Article filters` window.
@ -149,9 +152,9 @@ Here is the reference of methods and properties of some types available in your
| :--- | :--- | ---
| `Accept` | 1 | Message is accepted and will be added to DB or updated in DB.
| `Ignore` | 2 | Message is ignored and will **NOT** be added or updated in DB, but will also not be purged if already exists.
| `Purge` | 4 | Existing message is purged from the DB completely. Behavior is the same as `Ignore` when there is new incoming message.
| `Purge` | 4 | Existing message is purged from the DB completely. Behaves like `Ignore` when there is new incoming message.
Note that `MessageObject` attributes which can be synchronized with service are synchronized even if you return `Purge` or `Ignore`. In other words, even if your filter ignores the message, you can still tweak its properties which would be synchronized back to your server.
Note that `MessageObject` attributes are synchronized with service even if you return `Purge` or `Ignore`. In other words, even if your filter ignores the article, you can still tweak its properties which will be synchronized back to your server.
#### `DuplicationAttributeCheck` enum
| Enumerant name | Integer value | Description
@ -304,7 +307,7 @@ function filterMessage() {
Make sure that your receive only one message/article with particular URL across all your feeds (from same plugin) and all other messages with same URL are subsequently ignored:
```js
function filterMessage() {
if (msg.isDuplicateWithAttribute(MessageObject.SameUrl | MessageObject.AllFeedsSameAccount)) {
if (msg.isAlreadyInDatabase(MessageObject.SameUrl | MessageObject.AllFeedsSameAccount)) {
return MessageObject.Ignore;
}
else {
@ -329,19 +332,19 @@ RSS Guard offers additional advanced features inspired by [Liferea](https://lzon
You can select source type of each feed. If you select `URL`, then RSS Guard simply downloads feed file from given location and behaves like everyone would expect.
However, if you choose `Script` option, then you cannot provide URL of your feed and you rely on custom script to generate feed file and provide its contents to **standard output**. Resulting data written to standard output should be valid feed file, for example RSS or ATOM XML file.
However, if you choose `Script` option, then you cannot provide URL of your feed and you rely on custom script to generate feed file and provide its contents to [standard output](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)). Data written to standard output should be valid feed file, for example RSS or ATOM XML file.
`Fetch it now` button also works with `Script` option. Therefore, if your source script and (optional) post-process script in cooperation deliver a valid feed file to the output, then all important metadata, like title or icon of the feed, can be discovered :sparkles: automagically :sparkles:.
<img alt="alt-img" src="images/scrape-source-type.png" width="350px">
Any errors in your script must be written to **error output**.
Any errors in your script must be written to [error output](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)).
> **As of RSS Guard 4.1.3, you do not have to separate your arguments with `#`. If your argument contains spaces, then enclose it with DOUBLE quotes, for example `"my argument"`. DO NOT use SINGLE quotes to do that.**
> **As of RSS Guard 4.2.0, you do not have to separate your arguments with `#`. If your argument contains spaces, then enclose it with DOUBLE quotes, for example `"my argument"`. DO NOT use SINGLE quotes to do that.**
If everything went well, script must return `0` as the process exit code, or a non-zero exit code if some error happened.
If everything goes well, script must return `0` as the process exit code, or a non-zero exit code if some error happened.
Binary name (interpreter) must be always be specified, while arguments not. Be very careful when quoting arguments. Some examples of valid and tested execution lines are:
Executable file must be always be specified, while arguments not. Be very careful when quoting arguments. Some examples of valid and tested execution lines are:
| Command | Explanation |
| :--- | --- |
@ -357,7 +360,7 @@ RSS Guard offers [placeholder](#userd-plac) `%data%` which is automatically repl
Also, working directory of process executing the script is set to point to RSS Guard's user data folder.
There are some examples of website scrapers [here](https://github.com/martinrotter/rssguard/tree/master/resources/scripts/scrapers), most of them are written in Python 3, thus their execution line is similar to `python#script.py`. Make sure to examine each script for more information on how to use it.
There are some examples of website scrapers [here](https://github.com/martinrotter/rssguard/tree/master/resources/scripts/scrapers), most of them are written in Python 3, thus their execution line is similar to `python script.py`. Make sure to examine each script for more information on how to use it.
After your source feed data are downloaded either via URL or custom script, you can optionally post-process the data with one more custom script, which will take **raw source data as input** and must produce processed valid feed data to **standard output** while printing all error messages to **error output**.
@ -371,10 +374,10 @@ It's completely up to you if you decide to only use script as `Source` of the sc
### Notifications <a id="notif"></a>
RSS Guard allows you to configure behavior of desktop notifications. There is a number of events which can be configured:
* New (unread) articles fetched
* Fetching of articles is started
* Login OAuth tokens are refreshed
* New RSS Guard version is available
* New (unread) articles fetched.
* Fetching of articles is started.
* Login OAuth tokens are refreshed.
* New RSS Guard version is available.
* etc.
<img alt="alt-img" src="images/notif.png" width="600px">

4
src/librssguard/core/messageobject.cpp
View File

@ -18,6 +18,10 @@ void MessageObject::setMessage(Message* message) {
m_message = message;
}
bool MessageObject::isAlreadyInDatabase(DuplicationAttributeCheck attribute_check) const {
return isDuplicateWithAttribute(attribute_check);
}
bool MessageObject::isDuplicate(DuplicationAttributeCheck attribute_check) const {
return isDuplicateWithAttribute(attribute_check);
}

1
src/librssguard/core/messageobject.h
View File

@ -78,6 +78,7 @@ class MessageObject : public QObject {
// Check if message is duplicate with another messages in DB.
// Parameter "attribute_check" is DuplicationAttributeCheck enum
// value casted to int.
Q_INVOKABLE bool isAlreadyInDatabase(MessageObject::DuplicationAttributeCheck attribute_check) const;
Q_INVOKABLE bool isDuplicate(MessageObject::DuplicationAttributeCheck attribute_check) const;
Q_INVOKABLE bool isDuplicateWithAttribute(MessageObject::DuplicationAttributeCheck attribute_check) const;