From d7a14f8ce38502c23f067d270cd073d0b3fbbbd3 Mon Sep 17 00:00:00 2001 From: Martin Rotter Date: Thu, 12 Aug 2021 13:00:42 +0200 Subject: [PATCH] new docs --- .../desktop/com.github.rssguard.appdata.xml | 2 +- resources/docs/Documentation.md | 629 +++++++++++------- resources/docs/Downloads.md | 30 - resources/docs/Feed-formats.md | 46 -- resources/docs/Labels.md | 20 - resources/docs/Message-filters.md | 232 ------- resources/docs/images/add-acc.png | Bin 16728 -> 0 bytes resources/docs/images/cleanup-db.png | Bin 11282 -> 0 bytes resources/docs/images/ext-tools-message.png | Bin 942337 -> 0 bytes resources/docs/images/ext-tools-web.png | Bin 900194 -> 0 bytes resources/docs/images/feedly-details.png | Bin 21272 -> 0 bytes resources/docs/images/filters-dialog.png | Bin 0 -> 88508 bytes resources/docs/images/gmail-context-menu.png | Bin 96801 -> 0 bytes resources/docs/images/gmail-new-email.png | Bin 7714 -> 0 bytes .../docs/images/greader-api-settings.png | Bin 19935 -> 0 bytes resources/docs/images/gui-dark.png | Bin 0 -> 192920 bytes resources/docs/images/gui-dark2.png | Bin 0 -> 122570 bytes resources/docs/images/im-ex-feeds-dialog.png | Bin 21312 -> 0 bytes resources/docs/images/im-ex-feeds.png | Bin 63571 -> 0 bytes resources/docs/images/intel.png | Bin 0 -> 34918 bytes resources/docs/images/notif.png | Bin 0 -> 43054 bytes resources/docs/images/rss-context-menu.png | Bin 38443 -> 0 bytes resources/docs/images/scrape-post.png | Bin resources/docs/images/screenshot-linux.png | Bin 165703 -> 0 bytes resources/docs/images/screenshot-windows.png | Bin 98407 -> 0 bytes resources/docs/videos/hiding-gui.gif | Bin 1657513 -> 0 bytes src/librssguard/core/messageobject.cpp | 8 + src/librssguard/services/abstract/rootitem.h | 1 + .../services/greader/definitions.h | 2 +- .../services/greader/greadernetwork.cpp | 2 +- 30 files changed, 387 insertions(+), 585 deletions(-) mode change 100644 => 100755 resources/docs/Documentation.md delete mode 100755 resources/docs/Downloads.md delete mode 100755 resources/docs/Feed-formats.md delete mode 100755 resources/docs/Labels.md delete mode 100755 resources/docs/Message-filters.md delete mode 100755 resources/docs/images/add-acc.png delete mode 100755 resources/docs/images/cleanup-db.png delete mode 100755 resources/docs/images/ext-tools-message.png delete mode 100755 resources/docs/images/ext-tools-web.png delete mode 100755 resources/docs/images/feedly-details.png create mode 100755 resources/docs/images/filters-dialog.png delete mode 100644 resources/docs/images/gmail-context-menu.png delete mode 100644 resources/docs/images/gmail-new-email.png delete mode 100644 resources/docs/images/greader-api-settings.png create mode 100755 resources/docs/images/gui-dark.png create mode 100755 resources/docs/images/gui-dark2.png delete mode 100644 resources/docs/images/im-ex-feeds-dialog.png delete mode 100644 resources/docs/images/im-ex-feeds.png create mode 100755 resources/docs/images/intel.png create mode 100755 resources/docs/images/notif.png delete mode 100644 resources/docs/images/rss-context-menu.png mode change 100644 => 100755 resources/docs/images/scrape-post.png delete mode 100755 resources/docs/images/screenshot-linux.png delete mode 100755 resources/docs/images/screenshot-windows.png delete mode 100755 resources/docs/videos/hiding-gui.gif diff --git a/resources/desktop/com.github.rssguard.appdata.xml b/resources/desktop/com.github.rssguard.appdata.xml index 48323e46e..b80a56a2b 100644 --- a/resources/desktop/com.github.rssguard.appdata.xml +++ b/resources/desktop/com.github.rssguard.appdata.xml @@ -30,7 +30,7 @@ https://martinrotter.github.io/donate/ - + none diff --git a/resources/docs/Documentation.md b/resources/docs/Documentation.md old mode 100644 new mode 100755 index bf44752b1..e36be04a2 --- a/resources/docs/Documentation.md +++ b/resources/docs/Documentation.md @@ -1,117 +1,289 @@ -# Documentation -* [RSS Guard overview](#overview) - * [List of main features](#list-of-main-features) - * [Core concepts](#core-concepts) - * [Web-based and lite app variants](#web-based-and-lite-app-variants) - * [RSS Guard 3 vs RSS Guard 4](#rss-guard-3-vs-rss-guard-4) - * [Supported feed formats and online feed services](Feed-formats.md) - * [Message filtering](Message-filters.md) - * [Database backends](#database-backends) - * [Websites scraping](#websites-scraping) - * [Google Reader API](#google-reader-api) - * [Gmail](#gmail) - * [Feedly](#feedly) - * [Labels](Labels.md) - * [Notifications](#notifications) - * [Downloading files](#downloading-files) - * [External tools](#external-tools) - * [AdBlock](#adblock) - * [GUI tweaking](#gui-tweaking) -* [Miscellaneous topics](#miscellaneous-topics) - * [Download](Downloads.md) - * [How to contribute](#how-to-contribute) - * [Reporting bugs](#reporting-bugs) - * [Localizations](#localizations) - * [Videos](#videos) - * [Command line interface](#cli) - * [How to build](#how-to-build) - * [`%data%` placeholder](#data-placeholder) - * [Cleaning database](#cleaning-database) - * [Portable user data](#portable-user-data) - * [Downloading new messages](#downloading-new-messages) - * [Synchronization algorithms](#synchronization-algorithms) - * [Generating debug log file](#generating-debug-log-file) +# 🔥 RSS Guard Documentation 🔥 - +Welcome to RSS Guard documentation. You can find everything about the application right here. -# Overview -RSS Guard is simple feed reader. It is able to fetch the most known feed formats, including RSS/RDF/ATOM/JSON. RSS Guard is developed on top of the [Qt library](http://qt-project.org) and it supports these operating systems: +## Table of Contents +### [`What is RSS Guard?`](#wirss) +### [`Downloads`](#dwn) +### [`Supported Operating Systems`](#sos) +### [`Major Features`](#mfe) +#####     [`Supported Feed Readers`](#sfr) +#####     [`Article Filtering`](#fltr) +#####     [`Websites Scraping`](#scrap) +#####     [`Notifications`](#notif) +#####     [`Database Backends`](#datab) +#####     [`User Data Portability`](#userd) +#####     [`Built-in Web Browser with AdBlock`](#webb) +### [`Minor Features`]() +#####     [`Files Downloader`](#downl) +#####     [`Labels`](#lbls) +#####     [`GUI Tweaking`](#guit) +#####     [`Command Line Interface (CLI)`](#cli) +### [`For Contributors`](#contrib) +#####     [`Donations`](#donat) +#####     [`Compiling RSS Guard`](#compil) +#####     [`Plugin API`](#papi) +#####     [`Reporting Bugs or Feature Requests`]() +#####     [`Localization`]() -* Windows, -* GNU/Linux, -* Mac OS X, -* OS/2 (ArcaOS, eComStation), -* Android (prebuilt binaries N/A at this point). +
-## List of main features -* **support for online feed synchronization via plugins**, - * Tiny Tiny RSS, - * Nextcloud News, - * Inoreader, - * Gmail. - * Google Reader API (FreshRSS, The Old Reader, Bazqux, Reedah and others), - * Feedly. -* core: - * support for all feed formats (RSS/RDF/ATOM/JSON) including podcasts, - * import/export of feeds to/from OPML 2.0, - * possibility of using custom 3rd-party feed [synchronization services](Feed-formats.md), - * feed metadata fetching including icons, - * support for [scraping websites](#websites-scraping) which do not offer RSS/ATOM feeds and other related advanced features, - * scriptable [message filtering](#message-filtering), - * downloader with own tab and support for up to 6 parallel downloads, - * network proxy support, - * enhanced feed auto-updating with separate time intervals, - * "portable" mode support with clever auto-detection, - * [external tools](#external-tools) - you can run your program with article URL, - * handles tons of messages & feeds, - * ability to backup/restore database or settings, - * multiple data backend support, - * SQLite, - * MariaDB. - * support for `feed://` URI scheme. +## What is RSS Guard? +RSS Guard is desktop [open-source](https://en.wikipedia.org/wiki/Open_source) [cross-platform](#sos) [multi-protocol](#sfr) feed reader. It is able to fetch basically all known feed formats, including RSS/RDF/ATOM/JSON. RSS Guard is developed on top of the [Qt library](http://qt-project.org). -## Core concepts -RSS Guard is multi-protocol and multi-account application. If you start it for the first time, `Add account` dialog will pop-up. +## Downloads +Official place to download RSS Guard is at [Github Releases](https://github.com/martinrotter/rssguard/releases). You can also download development (beta) [build](https://github.com/martinrotter/rssguard/releases/tag/devbuild) which is automatically updated everytime source code is updated. - +Also, RSS Guard is [available](https://repology.org/project/rssguard/versions) for many Linux distributions, even via [Flathub](https://flathub.org/apps/details/com.github.rssguard). -You can also display this dialog from main menu `Accounts -> Add new account`. +I highly recommend to download RSS Guard only from reputable sources. -You must have added some account to start using RSS Guard. Each account provides access to some specific online service while `Standard online feeds` account is there to provide access to classic `RSS` and `ATOM` feeds. You can have activated many accounts in the same time and even multiple accounts of the same type, for example two distinct `Gmail` accounts. +## Supported Operating Systems +RSS Guard is cross-platform application and at this point is know to work on: +* Windows 7+ +* GNU/Linux (including PinePhone and other Linux-based phone operating systems) +* macOS 10.10+ +* OS/2 (ArcaOS, eComStation) -## Web-based and lite app variants -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 who doesn't care about memory consumption too much. Also, installation packages are relatively big. +## Major Features - +### Supported Feed Readers +RSS Guard is multi-account application and supports many web feed readers via built-in [plugins](#papi). One of the plugins, of course, provide support for standard **RSS/ATOM/JSON** feeds with set of features everyone would expect from classic feed reader like OPML support etc. -* **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 and offers faster GUI response in some use-cases. +I organized supported web feed readers into elegant table. - +| Service | Two-way Synchronization | [Intelligent Synchronization Algorithm](#intel) | Synchronized Labels | OAuth | +|----|-----|-----|----|---| +| Feedly | ✅ | ❌ | ✅ | ✅ (only for official binaries) | +| Gmail | ✅ | ❌ | ❌ | ✅ | +| Google Reader | ✅ | ✅ | ✅ | ✅ (only for Inoreader) | +| Nextcloud News | ✅ | ❌ | ❌ | ❌ | +| Tiny Tiny RSS | ✅ | ❌ | ✅ | ❌ | -If you're not sure which version to use, **use the WebEngine-based RSS Guard**. +Note that [labels](#lbls) are supported for all plugins, it's just that on some plugins they are local-only and are not synchronizeable to/from service, usually because service itself does not support the feature. -## RSS Guard 3 vs. RSS Guard 4 -RSS Guard 4 is **NOT** backwards compatible with previous editions of the application!!! It stores settings in slightly different [folder](#portable-user-data) to not overwrite user data from previous versions. +#### Intelligent Synchronization Algorithm +Some plugins support next-gen intelligent synchronization algorithm (ISA) which has some benefits as it usually offers superier synchronization speed and transfers much less data over your network connection. -RSS Guard 4 contains numerous enhancements and many of them are hidden under the hood and they make application easier to maintain, easier to improve and easier to use. + -## Database backends -RSS Guard offers switchable database backends which hold your data. At this point, two backends are available: -* MariaDB, -* SQLite (default). +In ISA, RSS Guard only downloads only articles which are new or were updated, whereas older algorithm in RSS Guard usually always fetches all available articles, even if they are not needed, leading to unnecessary overload of your network connection and RSS Guard. -SQLite backend is very simple to use, no further configuration is needed and all your data is stored in single file +### Article Filtering +Sometimes yout need to tweak incoming article - mark them starred, remove ads from their contents or simply ignore them. That's what filtering feature is for. + + + +#### Writing article filter +Article filters are fully scriptable and consist of arbitrary JavaScript code which must provide function with prototype + +```js +function filterMessage() { } ``` -\database\local\database.ini + +The function must be fast and must return values which belong to enumeration [`FilteringAction`](#FilteringAction-enum). You can you use either 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`. + +Each message 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 writable, allowing you to change contents of the message before it is written to DB. You can mark message important, parse its description or perhaps change author name or even assign some label to it!!! + +You can use [special placeholders](#userd-plac) within message 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 list of labels assigned to each message. You can therefore do 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. + +Passed message also offers special function +```js +Boolean MessageObject.isDuplicateWithAttribute(DuplicationAttributeCheck) ``` -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 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. MySQL will also work much better if you prefer to have zillions of feeds and messages stored. +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. -For database-related configuration see `Settings -> Data storage` dialog. +For example if you want to check if there is already another message with same author in database, then you 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)`. -## Websites scraping +Here is the reference of methods and properties of some types available in your filtering scipts. + +#### `MessageObject` class +| Property/method | Description | +|---|---| +| `Array