@@ -22,7 +16,11 @@ sort_by = "weight"
-`rsspls` generates RSS feeds from web pages. Example use cases: +About +----- + +`rsspls` generates RSS feeds from web pages using [CSS selectors][selectors] to extracts +parts of the page to turn into a feed. Example use cases: * Create a feed for a blog that does not have one so that you will know when there are new posts. @@ -33,13 +31,28 @@ sort_by = "weight" * Create a feed of the product page for a company, so you know when new products are added. -The idea is that you will then subscribe to the generated feeds in your feed -reader. This will typically require the feeds to be hosted via a web server. +You can subscribe to the generated feeds in your feed reader, either by +referring to them locally or by publishing them on a web server. -Credits -------- +
+Install
+Documentation
+
-* [RSS feed icon](http://www.feedicons.com/) by The Mozilla Foundation
+FAQ
+---
+
+Frequently anticipated questions:
+
+* _Does `rsspls` require a runtime or dependencies?_+ No. It's implemented in Rust and is a single-file native binary. +* _The screenshot at the top of the page looks like classic Mac OS. + Does it run on this system?_
+ No. The screenshot _is_ from Mac OS 8 but it shows a [ssheven] window + logged in to a Linux system running `rsspls`. +* _Why did you use a screenshot from Mac OS 8?_
+ I didn't want the screenshot to look like it was from any particular + modern system, so I picked an old one with a great design. Licence ------- @@ -51,8 +64,11 @@ This project is dual licenced under either of: at your option. -[rustup]: https://www.rust-lang.org/tools/install -[toml]: https://toml.io/ +Credits +------- + +* [RSS feed icon](http://www.feedicons.com/) by The Mozilla Foundation +* Website theme based on [Juice](https://github.com/huhu/juice) by HuHu + [selectors]: https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors -[cron]: https://en.wikipedia.org/wiki/Cron -[timers]: https://wiki.archlinux.org/title/Systemd/Timers +[ssheven]: https://github.com/cy384/ssheven diff --git a/content/documentation.md b/content/documentation.md index 24342fd..cde1fbf 100644 --- a/content/documentation.md +++ b/content/documentation.md @@ -4,7 +4,49 @@ description = "Documentation" weight = 2 +++ -### Configuration +## How it Works + +`rsspls` fetches each page specified by the configuration and extracts elements +from the page using [CSS selectors][selectors]. For example elements are matched +to determine the title and content of the feed entry. The generated feeds are +written to an output directory. HTTP caching is used to only update the feed +when the source page changes. + +## Supported Platforms + +`rsspls` should work on all [platforms supported by the Rust compiler][platforms] +including Linux, macOS, Windows, and BSD. Pre-compiled binaries are available +for common platforms. See [the install page](@/install.md) for details. + +## Usage + +``` +rsspls [OPTIONS] -o OUTPUT_DIR + +OPTIONS: + -h, --help + Prints this help information + + -c, --config + Specify the path to the configuration file. + $XDG_CONFIG_HOME/rsspls/feeds.toml is used if not supplied. + + -o, --output + Directory to write generated feeds to. + + -V, --version + Prints version information + +FILES: + ~/$XDG_CONFIG_HOME/rsspls/feeds.toml rsspls configuration file. + ~/$XDG_CONFIG_HOME/rsspls Configuration directory. + ~/XDG_CACHE_HOME/rsspls Cache directory. + + Note: XDG_CONFIG_HOME defaults to ~/.config, XDG_CACHE_HOME + defaults to ~/.cache. +``` + +## Configuration Unless specified via the `--config` command line option `rsspls` reads its configuration from one of the following paths: @@ -20,7 +62,7 @@ The configuration file is in [TOML][toml] format. The parts of the page to extract for the feed are specified using [CSS selectors][selectors]. -#### Annotated Sample Configuration +### Annotated Sample Configuration The sample file below demonstrates all the parts of the configuration. @@ -135,49 +177,172 @@ The first example above (for my blog WezM.net) matches HTML that looks like this ``` -#### More Detail on Date Handling +### output -The `date` key in the configuration can be a string or a table. If it's a -string then it's used as selector to find the element containing the date and -`rsspls` will attempt to automatically parse the value. If automatic parsing -fails you can manually specify the format using the table form of `date`: +Optional output directory to write the feeds to. If not specified it must be +supplied via the `--output` command line option. Directory will be created if +it does not exist. + +### proxy + +Optional proxy address. If specified, all requests will be routed through it. +The address needs to be in the format: `protocol://ip_address:port` +The supported protocols are: http, https, socks and socks5h. + +The proxy for http and https requests can also be specified with the +environment variables `http_proxy` and `HTTPS_PROXY` respectively. +The config file takes precedence over environment variables. + +### feed.title + +The title of the channel in the generated feed. + +### feed.filename + +The output filename to write this feed to. Note: this is a filename only, not a +path. It should not contain slashes. It will be written to the [output](#output) +directory. + +### feed.config.url + +The URL of the web page to generate the feed from. The page at this address +will be fetched processed to turn it into a feed. + +### feed.config.item + +A CSS selector to select elements on the page that represent items in the feed. +The other CSS selectors match elements inside the elements that this selector +matches. + +### feed.config.heading + +A CSS selector relative to `item` to an element that will supply the title for +the item in the feed. + + +### feed.config.link + +CSS selector relative to `item` to an element that will supply the +link for the item in the feed. + +**Note:** This element must have a `href` attribute. + +**Note:** If not supplied `rsspls` will attempt to use the +`feed.config.heading` selector as the `link` element for backwards compatibility +with earlier versions. A warning message will be emitted in this case. It is +recommended to specify the `link` selector explicitly. + + +### feed.config.summary + +Optional CSS selector relative to `item` that will supply the content of the RSS item. + +### feed.config.date + +The optional `date` key in the configuration can be a string or a table. If it's a +string then it's used as CSS selector relative to `item` to find the element +containing the date and `rsspls` will attempt to automatically parse the value. + +If automatic parsing fails you can manually specify the format using the table +form of `date`, which looks like this: ```toml [feed.config.date] selector = "time" # required type = "Date" -format = "[day padding:none]/[month padding:none]/[year]" +format = "[day padding:none]/[month padding:none]/[year]" # will parse 1/2/1934 style dates ``` -* `type` is `Date` when you want to parse just a date. Use `DateTime` if you're - parsing a date and time with the format. Defaults to `DateTime`. -* `format` is a format description using the syntax described on this page: -