From 1b65694e053c5e1cc3900f50d244a47a2144a114 Mon Sep 17 00:00:00 2001 From: "Daniel J. Summers" Date: Sun, 26 May 2024 22:17:47 -0400 Subject: [PATCH] WIP on docs (#1) --- .../docs/{refresh-feeds.php => feeds.php} | 36 ++++++++-- src/public/docs/index.php | 27 ++++++-- src/public/docs/items.php | 69 +++++++++++++++++++ 3 files changed, 120 insertions(+), 12 deletions(-) rename src/public/docs/{refresh-feeds.php => feeds.php} (56%) create mode 100644 src/public/docs/items.php diff --git a/src/public/docs/refresh-feeds.php b/src/public/docs/feeds.php similarity index 56% rename from src/public/docs/refresh-feeds.php rename to src/public/docs/feeds.php index f5812af..0f9f2e0 100644 --- a/src/public/docs/refresh-feeds.php +++ b/src/public/docs/feeds.php @@ -4,15 +4,37 @@ include '../../start.php'; $db = Data::getConnection(); Security::verifyUser($db, redirectIfAnonymous: false); -page_head('Refresh Feeds | Documentation'); ?> -

Refresh Feeds

+page_head('Feeds | Documentation'); ?> +

Feeds

-

Manual Feed Refresh

-

Next to the “Your Unread Items” heading on the main page, there is a link labeled “Refresh All - Feeds”. Clicking this link will reload the main page once the feeds have been refreshed. Depending on the - number and size of feeds, this may take a bit of time; each feed is refreshed individually. -

Automatic Refreshing

+

Adding a Feed

+

On the top menu bar, click the Feeds link, then click the Add Feed button. In + the field that is displayed, enter the + URL for the feed. Then click the + Save button; if all goes well, the application will subscribe to the feed and pull in all its + current items. +

If you do not have the feed’s direct link, you can enter the URL for the site that hosts the feed. In most + cases, the application should be able to find it and subscribe to it. +

Editing a Feed’s URL

+

If the feed to which you are subscribed has moved, you can edit the URL of the feed. In this case, the + application will confirm that the new feed exists and will synchronize with its items. Depending on how the feed + was moved, this may result in items reappearing as new; however, bookmarked items will not be removed, and older + items will not be removed until they would otherwise have been pruned. +

Deleting a Feed

+

On the Feeds page, below each feed’s title, there is a Delete link at the + end of the line. Once that is clicked, you will be prompted to confirm that you really mean to delete this feed; + if you confirm the deletion, the feed and all its items (including bookmarked items) will be deleted. +

Refreshing Feeds

+

Feeds are pulled when their subscriptions are added; however, a one-time pull of feeds does not keep us up to + date on future posts. From within the application, feeds can be updated manually; there is also a way to set up + a job to regularly refresh feeds. +

Manual Refresh

+

Next to the “Your Unread Items” heading on the main page, there is a link labeled + Refresh All Feeds. Clicking this link will reload the main page once the feeds have been + refreshed. Depending on the number and size of feeds, this may take a bit of time; each feed is refreshed + individually. +

Automatic Refresh Job (Linux / Mac)

The refresh utility script will perform this refresh from the CLI. As it runs, it will list the feeds as it processes them, and if it encounters any errors, that is noted as well. This process can be automated via cron on Linux or Mac systems. This is most easily implemented by writing a small diff --git a/src/public/docs/index.php b/src/public/docs/index.php index 1811c50..ba3bea1 100644 --- a/src/public/docs/index.php +++ b/src/public/docs/index.php @@ -7,11 +7,28 @@ Security::verifyUser($db, redirectIfAnonymous: false); page_head('Documentation'); ?>

Documentation Home

-

provides orientation on Feed Reader Central’s command line - interface -

describes the three security modes and how to - manage each of them -

has instructions on how feeds can be refreshed on a schedule +

About the Application

+

This application is designed to be a lightweight, near-zero dependency application that individuals can run + themselves. The idea that let to its creation was a desire to have a set of + RSS feeds which could be read from multiple devices on the same + home network; for example, if an item was read from a laptop, it would not show up as new if the feed were read + from a phone. The author had planned to write something similar when Google Reader shut down, and the + combination of those two ideas led to the application you are looking at now. +

Installation

+

Steps to install this application are found in the Feed Reader Central source + code repository. It also describes some required configuration (mostly surrounding security modes; see the first + feature below for all the details on that) and some optional ways to change the application's behavior. +

Usage

+

– Feed Reader Central can be as secure as you require it + to be. Learn about the modes available, their suitability for private networks or the open Internet, and how to + manage users in a multi-user instance. +

– Without feeds, this application is just a bunch of near-empty pages; + this page describes how to add and maintain feeds. +

– Read the items from feeds, bookmark them, search for text within them, + and more. +

(CLI) – Feed Reader Central provides several functions + that can be performed via its command line interface.

close(); diff --git a/src/public/docs/items.php b/src/public/docs/items.php new file mode 100644 index 0000000..7360e51 --- /dev/null +++ b/src/public/docs/items.php @@ -0,0 +1,69 @@ + +

Items

+

+

+

Reading an Item

+

Before we look at all the different ways you can produce lists of items, we will take a quick look at how the + item page works. Within a list of items, this page can be accessed via the title of the item. +

    +
  • The title of the items is a link to the item at its original source; it will open in a new tab. +
  • The bookmark icon shows its current bookmark status; gray is not bookmarked, green is bookmarked. Clicking + the icon will toggle the status for the item. If the current user has any bookmarked items, a + Bookmarked item will appear in the top menu bar. + (The application usually does not replace the menu bar; clicking the + Feed Reader Central link will reload it.) +
  • Below the title, the source, published date, and updated date (if applicable) are displayed. +
  • The text of the item is displayed. Images are constrained to be no wider than the screen on which they are + being viewed, but other embedded objects (YouTube videos, etc.) with specific sizes may end up overflowing. + (Web devs, if you have any ideas on how to constrain those as well, I'm all ears…) +
  • Below the text, there are three buttons. Done leaves the item marked as having been read, + Keep as New will mark the item as unread, and Delete will delete the item + from the database. Any of them will return you to wherever you were when you clicked the title of the item. +
+

Viewing Items for All Feeds

+

There are three different ways to view items across all your subscriptions. +

Unread Items

+

The main page of the application (after logging on, if required) displays all currently unread items across all + subscribed feeds. The name of the feed is a link to view just that feed’s unread items. +

Bookmarked Items

+

If you have any bookmarked items, the Bookmarked link in the top menu bar will bring you to a + list of all those items. The name of the feed is a link to view just that feed’s bookmarked items. +

Searching for Items

+

The Search link in the top menu bar presents a box where search text can be entered; you can + also choose whether to search all items, or only those that have been bookmarked. The search applies to the + content of each item. Within the search results, there is an indicator displayed if the item is unread or + bookmarked, and the name of the feed is not linked. +

Under the hood, this uses + SQLite’s FTS5, + so it is case-insensitive by default and provides some interesting ways to query your items. +

    +
  • election would return items with the word “election” in them. +
  • senat* would return items with words like “Senator”, “senatorial”, or + “Senate” in them. +
  • "election 2024" (note the quotes) would return items that have the phrase + “Election 2024” in them; election 2024 would return items that have either + “election” or “2024” in them. +
  • election AND 2024 is the same as above; AND requires that both conditions be + satisfied. (OR is also supported; both these must be uppercase.) +
  • election NOT president* would return items containing “election”, but only if they + did not have words like “president” or “presidential”. +
+

Viewing Items by Feed

+

Other than the unread and bookmarked links mentioned above, lists of items by feed are linked on the + Feeds page. Below each feed’s title, there are links for All, + Unread, and Bookmarked, along with a count of items that fit the status. + (If there are no items, the word is not linked.) +

A Note on Sorting

+

All lists of items are sorted by date, with the most recent items on top. Both the RSS and Atom specifications + provide both a published date and an updated date. When selecting a date for sorting, the application uses the + updated date if it is present; otherwise, it uses the published date. Some sites update their items more than + others; if the items seem to move around in the list after a refresh, this is likely the cause. +

close();