\s*Ads[\S\s]+Remove<\/a>[\S\s]+adv\/www\/delivery[\S\s]+?<\/div>/im, '');
@@ -292,34 +291,34 @@ function filterMessage() {
}
```
-###
Websites Scraping
-> **Only proceed if you consider yourself to be a power user and you know what you are doing!**
+### Websites Scraping
+> **[CAUTION!] Only proceed if you consider yourself a power user and you know what you are doing!**
-RSS Guard offers extra advanced features which are inspired by [Liferea](https://lzone.de/liferea/).
+RSS Guard offers additional advanced features inspired by [Liferea](https://lzone.de/liferea/).
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.
-`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 automagically discovered.
+`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:.
-
+
Any errors in your script must be written to **error output**.
Note that you must provide full execution line to your custom script, including interpreter binary path and name and all that must be written in special format `
###....`. The `#` character is there to separate interpreter and individual arguments. I had to select some character as separator because simply using space ` ` is not that easy as it might sound, as sometimes space could be a part of an argument itself.
-Used script must return `0` as process exit code if everything went well, or non-zero exit code if some error happened.
+If everything went 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 provided in all cases, arguments do not have to be. Also be very carefully about arguments quoting. Some examples of valid and tested execution lines are:
-
-| Command | Explanation |
-|---------|-------------|
-| `bash#-c#curl https://github.com/martinrotter.atom` | Downloads ATOM feed file with Bash and Curl. |
-| `Powershell#Invoke-WebRequest 'https://github.com/martinrotter.atom' \| Select-Object -ExpandProperty Content` | Downloads ATOM feed file with Powershell. |
-| `php#tweeper.php#-v#0#https://twitter.com/NSACareers` | Scrape Twitter RSS feed file with [Tweeper](https://git.ao2.it/tweeper.git). Tweeper is utility which is able to produce RSS feed from Twitter and other similar social platforms. |
+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:
-
+| Command | Explanation |
+| :--- | --- |
+| `bash#-c#curl https://github.com/martinrotter.atom` | Download ATOM feed file using Bash and Curl. |
+| `Powershell#Invoke-WebRequest 'https://github.com/martinrotter.atom' \| Select-Object -ExpandProperty Content` | Download ATOM feed file with Powershell. |
+| `php#tweeper.php#-v#0#https://twitter.com/NSACareers` | Scrape Twitter RSS feed file with [Tweeper](https://git.ao2.it/tweeper.git). Tweeper is the utility which is able to produce RSS feed from Twitter and other similar social platforms. |
+
+
Note that the above examples are cross-platform and you can use the exact same command on Windows, Linux or Mac OS X, if your operating system is properly configured.
@@ -333,40 +332,40 @@ After your source feed data are downloaded either via URL or custom script, you
Format of post-process script execution line is the same as above.
-
+
Typical post-processing filter might do things like advanced CSS formatting, localization of content to another language, downloading of full articles, some kind of filtering or removing ads.
It's completely up to you if you decide to only use script as `Source` of the script or separate your custom functionality between `Source` script and `Post-process` script. Sometimes you might need different `Source` scripts for different online sources and the same `Post-process` script and vice versa.
-### Notifications
+### Notifications
RSS Guard allows you to configure behavior of desktop notifications. There is a number of events which can be configured:
-* new (unread) messages downloaded,
-* downloading of messages started,
-* login OAuth tokens refreshed,
-* new RSS Guard version available,
-* ...
+* New (unread) articles fetched
+* Fetching of articles is started
+* Login OAuth tokens are refreshed
+* New RSS Guard version is available
+* etc.
-
+
Your notification can also play `.wav` sounds which you can place under your [user data folder](#userd) and use them via special [placeholder](#userd-plac). Other audio formats are not supported.
-### Database Backends
+### Database Backends
RSS Guard offers switchable database backends which hold your data. At this point, two backends are available:
-* MariaDB,
-* SQLite (default).
+* MariaDB
+* SQLite (default)
SQLite backend is very simple to use, no further configuration is needed and all your data is stored in single file
```
\database\local\database.db
```
-Check `About RSS Guard -> Resources` dialog to find more info on significant paths used. This backend offers "in-memory" database option, which automatically copies all your data into RAM when app starts and then works solely with that RAM data, which makes RSS Guard incredibly fast. Data is also written back to database file when app exits. Note that this option should be used very rarely because RSS Guard should be fast enough with classic SQLite persistent DB files. So only use this if your amounts of article data are huge and you know what you are doing.
+Check `About RSS Guard -> Resources` dialog to find more info on significant paths used. This backend offers "in-memory" database option, which automatically copies all your data into RAM when application launches, and then works solely with that RAM data, which makes RSS Guard incredibly fast. Data is also written back to database file when application exits. Note that this option should be used very rarely because RSS Guard should be fast enough with classic SQLite persistent DB files. Only use this with a huge amount of article data, and when you know what you are doing.
MariaDB (MySQL) backend is there for users, who want to store their data in a centralized way. You can have single server in your network and use multiple RSS Guard instances to access the data.
For database-related configuration see `Settings -> Data storage` dialog.
-### User Data Portability
+### User Data Portability
One of the main goals of RSS Guard is to have local application data portable (relocatable) so that they can be use across all [supported operating systems](#sos).
RSS Guard is able to run in two modes.
@@ -379,22 +378,22 @@ exists, then this user folder is used.
The other mode is that user data folder is placed in subfolder `data4` in the same directory as RSS Guard binary (`rssguard.exe` on Windows). This *"portable"* mode is automatically enabled if "non-portable" mode detection fails.
-#### `%data%` placeholder
+#### `%data%` placeholder
RSS Guard stores its data and settings in single folder. What exact folder it is is described [here](#portable-user-data). RSS Guard allows you to use the folder programmatically in some special contexts via `%data%` placeholder. You can use this placeholder in these RSS Guard contexts:
-* Contents of your [message filters](Message-filters.md) - you can therefore place some scripts under your user data folder and include it via `JavaScript` into your message filter.
+* Contents of your [article filters](#fltr) - you can, therefore, place some scripts under your user data folder and include them via `JavaScript` into your article filter.
* Contents of each file included in your custom [skins](#skin). Note that in this case, the semantics of `%data%` are little changed and `%data%` points directly to base folder of your skin.
* `source` and `post-process script` attributes of for [scraping](#scrap) feed - you can use the placeholder to load scripts to generate/process feed from user data folder.
* Notifications also support the placeholder in path to audio files which are to be played when some event happens. For example you could place audio files in your data folder and then use them in notification with `%data%\audio\new-messages.wav`. See more about notifications [here](#notif).
-### Built-in Web Browser with AdBlock
+### Built-in Web Browser with AdBlock
RSS Guard is distributed in two variants:
-* **Standard package with WebEngine-based bundled message viewer**: This variant displays messages with their full formatting and layout in embedded Chromium-based web viewer. This variant of RSS Guard should be nice for everyone. Also, installation packages are relatively big.
+* **Standard package with WebEngine-based bundled article viewer**: This variant displays messages/articles with their full formatting and layout in embedded Chromium-based web viewer. This variant of RSS Guard should be nice for everyone. Also, installation packages are relatively big.
-
+
-* **Lite package with simple text-based message viewer**: This variant displays message in much simpler and more lightweight text-based component. All packages of this variant have `nowebengine` keyword in their names. Layout and formatting of displayed message is simplified, no big external web viewers are used, which results in much smaller installation packages, much smaller memory footprint and increased privacy of the user, because many web resources are not downloaded by default like pictures, JavaScript and so on. This variant of RSS Guard is meant for advanced users.
+* **Lite package with simple text-based article viewer**: This variant displays message/article in much simpler and more lightweight text-based component. All packages of this variant have `nowebengine` keyword in their names. Layout and formatting of displayed message is simplified, no big external web viewers are used, which results in much smaller installation packages, much smaller memory footprint and increased privacy of the user, because many web resources are not downloaded by default like pictures, JavaScript and so on. This variant of RSS Guard is meant for advanced users.
-
+
If you're not sure which version to use, **use the WebEngine-based RSS Guard**.
@@ -403,60 +402,60 @@ If you're not sure which version to use, **use the WebEngine-based RSS Guard**.
You need to have have [Node.js](https://nodejs.org) with [NPM](https://www.npmjs.com) (which is usually included in Node.js installer) installed to have ad-blocking in RSS Guard working. Also, the implementation requires additional [npm](https://www.npmjs.com) modules to be installed. You see the list of needed modules near the top of [this](https://github.com/martinrotter/rssguard/blob/master/resources/scripts/adblock/adblock-server.js) file.
-I understand that the above installation of needed dependencies is not trivial, but it is necessary evil to have up-to-date and modern implementation of AdBlock in RSS Guard. Previous `C++`-based implementation was buggy, quite slow and hard to maintain.
+I understand that the above installation of needed dependencies is not trivial, but it is necessary evil to have up-to-date and modern implementation of AdBlock in RSS Guard. Previous, "C++"-based, implementation was buggy, quite slow, and hard to maintain.
-You can find elaborated lists of AdBlock rules [here](https://easylist.to). You can just copy direct hyperlinks to those lists and paste them into "Filter lists" textbox as seen below. Remember to always separate individual links with newlines. Same applies to "Custom filters" where you can insert individual filters, for example [filter](https://adblockplus.org/filter-cheatsheet) "idnes" to block all URLs with "idnes" in them.
+You can find elaborate lists of AdBlock rules [here](https://easylist.to). You can just copy direct hyperlinks to those lists and paste them into the "Filter lists" text-box as shown below. Remember to always separate individual links with newlines. Same applies to "Custom filters", where you can insert individual filters, for example [filter](https://adblockplus.org/filter-cheatsheet) "idnes" to block all URLs with "idnes" in them.
-
+
The way ad-blocking internally works is that RSS Guard starts local HTTP browser which provides ad-blocking API, which is subsequently called by RSS Guard. There is some caching done in between, which speeds up some ad-blocking decisions.
-## Minor Features
+## Minor Features
-### Files Downloader
+### Files Downloader
RSS Guard offers simple embedded file downloader.
-
+
-You can right click on any item in embedded web browser and hit `Save as` button. RSS Guard will then automatically display downloader and will download your file. This feature works in both RSS Guard [variants](#webb).
+You can right click on any item in embedded web browser and hit `Save as` button. RSS Guard will then automatically display the downloader, and will download your file. This feature works in [both RSS Guard variants](#webb).
-
+
You can download up to 6 files simultaneously.
-### Labels
-RSS Guard supports labels (tags). Arbitrary number of tags can be assigned to each and every message.
+### Labels
+RSS Guard supports labels (tags). Any number of tags can be assigned to any article.
-Also, note that tags in some plugins are [synchronizable](#sfrl). While labels are synchronized with these services, they sometimes cannot be directly created via RSS Guard and you have to create them via web interface of the respective service and then perform `Synchronize folders & other items` which will download newly created labels too.
+Note that tags in some plugins are [synchronizable](#sfrl). While labels are synchronized with these services, sometimes they cannot be directly created via RSS Guard. In this case, you have to create them via web interface of the respective service, and only after that perform `Synchronize folders & other items`, which will fetch newly created labels too.
-You can easily add labels via `Labels` root item.
+Labels can be easily added via `Labels` root item.
-
+
-You can choose title and color of your new label.
+New label's title and color can also be chosen.
-
+
-You can easily (de)assign label to messages in message viewer.
+Unassigning a message label might easily be done through the message viewer.
-
+
-Note that (de)assignments of labels to messages are synchronized back to supported servers in regular intervals.
+Note that unassigning a message labels is also synchronized at regular intervals (with services that support label synch).
Also, [message filters](#fltr) can assign or remove labels to/from messages.
-### Skins
-RSS Guard is skinable application. Its GUI can be almost completely styled with [stylesheets](https://doc.qt.io/qt-5/stylesheet.html).
+### Skins
+RSS Guard is a skin-able application. Its GUI can be almost completely styled with [stylesheets](https://doc.qt.io/qt-5/stylesheet.html).
-
+
You can select style and skin in settings category `User interface`.
RSS Guard encapsulates styling capabilities via *skins* feature. Each skin is placed in its own folder and must contain several [files](https://github.com/martinrotter/rssguard/tree/master/resources/skins/vergilius). There are some [built-in](https://github.com/martinrotter/rssguard/tree/master/resources/skins) skins, but you can place your custom skins in your [user data folder](#userd). You can find exact path to your user data folder in `About` dialog. Note that there must be subfolder `skins`. Create it if it does not exist and place your custom skins inside.
-Also, there is "empty" [skin](https://github.com/martinrotter/rssguard/tree/master/resources/skins/plain) which can be used as a base for your custom skins. Look into its main [layout file](https://github.com/martinrotter/rssguard/tree/master/resources/skins/plain/html_wrapper.html) for some commentary.
+The base for your custom skin may serve an empty ["plain" skin](https://github.com/martinrotter/rssguard/tree/master/resources/skins/plain). Look the [README file](https://github.com/martinrotter/rssguard/tree/master/resources/skins/plain/README) there, for some commentaries to it.
-
+
So for example if your new skin is called `greenland`, you must place it in folder
@@ -469,14 +468,14 @@ As stated above, there are several files in each skin:
* `theme.css` - [Qt stylesheet](https://doc.qt.io/qt-5/stylesheet.html) file.
* `html_*.html` - These are (partial) HTML files which are used by RSS Guard in various situations like displaying article or error page.
-### GUI Tweaking
+### GUI Tweaking
RSS Guard's main window appearance can be tweaked in many ways. You can hide menu, toolbars, status bar, you can also change orientation of article viewer to suit widescreen devices.
-
-
-
-
-
+
+
+
+
+
### Command Line Interface
RSS Guard offers CLI (command line interface). For overview of its features, run `rssguard --help` in your terminal. You will see the overview of the interface.
@@ -503,7 +502,7 @@ Arguments:
RSS Guard can add feeds passed as URLs via command line arguments. Feed URI [scheme](https://en.wikipedia.org/wiki/Feed_URI_scheme) is supported, so that you can call RSS Guard like this:
-```
+```powershell
rssguard.exe "feed://archlinux.org/feeds/news"
rssguard.exe "feed:https//archlinux.org/feeds/news"
rssguard.exe "https://archlinux.org/feeds/news"
@@ -520,18 +519,18 @@ You can support author of RSS Guard via [donations](https://github.com/sponsors/
RSS Guard is C++ application and all common build instructions can be found in top of [project file](https://github.com/martinrotter/rssguard/blob/master/build.pro).
### Plugin API
-RSS Guard offers simple `C++` API for creating new service plugins. All base API classes are in folder [`abstract`](https://github.com/martinrotter/rssguard/tree/master/src/librssguard/services/abstract). User must subclass and implement all interface classes:
+RSS Guard offers simple C++ API for creating new service plugins. All base API classes are in folder [`abstract`](https://github.com/martinrotter/rssguard/tree/master/src/librssguard/services/abstract). User must subclass and implement all interface classes:
-| Class | Purpose |
-|-------|---------|
-| `ServiceEntryPoint` | Very base class which provides basic information about the plugin name, author etc. It also provides methods which are called when new account should be created and when existing accounts should be loaded from database. |
-| `ServiceRoot` | This is the core "account" class which represents account node in feed's list and offers interface for all critical functionality of a plugin, including handlers which are called when starting/stoping a plugin, marking messages read/unread/starred/deleted, (de)assigning labels etc. |
+| Class | Purpose |
+| :--- | --- |
+| `ServiceEntryPoint` | Very base class which provides basic information about the plugin name, author, etc. It also provides methods which are called when new account should be created and when existing accounts should be loaded from database. |
+| `ServiceRoot` | This is the core "account" class which represents an account node in feed's list, and offers interface for all critical functionality of a plugin, including handlers which are being called with a plugin's start/stop, marking messages as read/unread/starred/deleted, unassigning labels, etc. |
API is reasonably simple to understand but relatively large. Sane default behavior is employed where it makes sense.
Perhaps the best approach to use when writing new plugin is to copy [existing](https://github.com/martinrotter/rssguard/tree/master/src/librssguard/services/greader) one and start from there.
-Note that RSS Guard can support loading of plugins from external libraries (dll, so, etc.) but the functionality must be polished because so far all plugins are directly bundled into the app as no one really requested run-time loading of plugins so far.
+Note that RSS Guard can support loading of plugins from external libraries (`.dll`, `.so`, etc.) but the functionality must be polished because so far all plugins are directly bundled into the application as no one really requested run-time loading of plugins so far.
### Reporting Bugs or Feature Requests
Please report all issues/bugs/ideas to [Issues](https://github.com/martinrotter/rssguard/issues) section. Describe your problem as precisely as possible, along with steps taken leading up to the issue occurring.
@@ -547,7 +546,7 @@ If you are interested in creating translations for RSS Guard, then do this:
1. Go [here](http://www.transifex.com/projects/p/rssguard) and check status of currently supported localizations.
2. [Login](http://www.transifex.com/signin) (you can use social networks to login) and work on existing translations. If no translation team for your country/language exists, then ask for creating of localization team via the website.
-**All translators commit themselves to keep their translations up-to-date. If some translations are not updated by their authors regularly and only small number of strings is translated, then those translations along with their teams will be eventually REMOVED from the project!!! At least 50% of strings must be translated for translation to being added to project.**
+**All translators commit themselves to keep their translations up-to-date. If some translations are not updated by their authors regularly, and only a small number of strings is translated then those translations along with their teams will eventually be REMOVED from the project!!! At least 50% of strings must be translated for translation to be added to project.**
### Migrating data
RSS Guard automatically migrates all your [user data](#userd) if you install newer minor version, for example if you update from `3.7.5` to `3.9.1`.
@@ -575,7 +574,7 @@ In `3.x.x` each plugin/account type had its own table where it kept your login u
Then you need to go to `Edit` dialog of your account in RSS Guard (once you complete this migration guide) and check for all missing login information etc.
-Also, once you add any rows the `Accounts` table, your row will be assigned uniqued `id` value which is integer and is used as foreign key in other DB tables, via column `account_id`.
+Also, once you add any rows the `Accounts` table, your row will be assigned unique `id` value which is integer and is used as foreign key in other DB tables, via column `account_id`.
### Converting `Feeds` table
***
@@ -595,13 +594,13 @@ There are some changes in `Feeds` table:
}
```
-Pay attention to `account_id` column as this column is the ID of your accout as stated in the above [section](#accid).
+Pay attention to `account_id` column as this column is the ID of your account as stated in the above [section](#accid).
### Converting `Messages` table
***
Columns were reordered and other than that new column `score` with sane default value was added. Therefore you can simply copy your data in a column-to-column mode.
-Pay attention to `account_id` column as this column is the ID of your accout as stated in the above [section](#accid).
+Pay attention to `account_id` column as this column is the ID of your account as stated in the above [section](#accid).
### Other tables
***
-
+