WIP on docs (#1)
This commit is contained in:
parent
da34f36530
commit
1b65694e05
@ -4,15 +4,37 @@ include '../../start.php';
|
||||
$db = Data::getConnection();
|
||||
Security::verifyUser($db, redirectIfAnonymous: false);
|
||||
|
||||
page_head('Refresh Feeds | Documentation'); ?>
|
||||
<h1>Refresh Feeds</h1>
|
||||
page_head('Feeds | Documentation'); ?>
|
||||
<h1>Feeds</h1>
|
||||
<p class=back-link><?=hx_get('./', '⟨⟨ Documentation Home')?>
|
||||
<article class=docs>
|
||||
<h2>Manual Feed Refresh</h2>
|
||||
<p>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.
|
||||
<h2>Automatic Refreshing</h2>
|
||||
<h2>Adding a Feed</h2>
|
||||
<p>On the top menu bar, click the <strong>Feeds</strong> link, then click the <strong>Add Feed</strong> button. In
|
||||
the field that is displayed, enter the
|
||||
<abbr title="Uniform Resource Locator (aka “link”)">URL</abbr> for the feed. Then click the
|
||||
<strong>Save</strong> button; if all goes well, the application will subscribe to the feed and pull in all its
|
||||
current items.
|
||||
<p>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.
|
||||
<h2>Editing a Feed’s URL</h2>
|
||||
<p>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.
|
||||
<h2>Deleting a Feed</h2>
|
||||
<p>On the <strong>Feeds</strong> page, below each feed’s title, there is a <strong>Delete</strong> 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.
|
||||
<h2>Refreshing Feeds</h2>
|
||||
<p>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.
|
||||
<h3>Manual Refresh</h3>
|
||||
<p>Next to the “Your Unread Items” heading on the main page, there is a link labeled
|
||||
<strong>Refresh All Feeds</strong>. 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.
|
||||
<h3>Automatic Refresh Job <em>(Linux / Mac)</em></h3>
|
||||
<p>The <code>refresh</code> 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 <code>cron</code> on Linux or Mac systems. This is most easily implemented by writing a small
|
||||
@ -7,11 +7,28 @@ Security::verifyUser($db, redirectIfAnonymous: false);
|
||||
page_head('Documentation'); ?>
|
||||
<h1>Documentation Home</h1>
|
||||
<article>
|
||||
<p><?=hx_get('./the-cli', 'About the CLI')?> provides orientation on Feed Reader Central’s command line
|
||||
interface
|
||||
<p><?=hx_get('./security-modes', 'Configuring Security Modes')?> describes the three security modes and how to
|
||||
manage each of them
|
||||
<p><?=hx_get('./refresh-feeds', 'Refresh Feeds')?> has instructions on how feeds can be refreshed on a schedule
|
||||
<h2>About the Application</h2>
|
||||
<p>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
|
||||
<abbr title="Really Simple Syndication">RSS</abbr> 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.
|
||||
<h2>Installation</h2>
|
||||
<p><a href=https://git.bitbadger.solutions/bit-badger/feed-reader-central/src/branch/main/INSTALLING.md
|
||||
target=_blank rel=noopener>Steps to install this application</a> 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.
|
||||
<h2>Usage</h2>
|
||||
<p><?=hx_get('./security-modes', 'Security Modes')?> – 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.
|
||||
<p><?=hx_get('./feeds', 'Feeds')?> – Without feeds, this application is just a bunch of near-empty pages;
|
||||
this page describes how to add and maintain feeds.
|
||||
<p><?=hx_get('./items', 'Items')?> – Read the items from feeds, bookmark them, search for text within them,
|
||||
and more.
|
||||
<p><?=hx_get('./the-cli', 'Command Line Interface')?> (CLI) – Feed Reader Central provides several functions
|
||||
that can be performed via its command line interface.
|
||||
</article><?php
|
||||
page_foot();
|
||||
$db->close();
|
||||
|
||||
69
src/public/docs/items.php
Normal file
69
src/public/docs/items.php
Normal file
@ -0,0 +1,69 @@
|
||||
<?php
|
||||
include '../../start.php';
|
||||
|
||||
$db = Data::getConnection();
|
||||
Security::verifyUser($db, redirectIfAnonymous: false);
|
||||
|
||||
page_head('Items | Documentation'); ?>
|
||||
<h1>Items</h1>
|
||||
<p class=back-link><?=hx_get('./', '⟨⟨ Documentation Home')?>
|
||||
<article class=docs>
|
||||
<h2>Reading an Item</h2>
|
||||
<p>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.
|
||||
<ul>
|
||||
<li>The title of the items is a link to the item at its original source; it will open in a new tab.
|
||||
<li>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
|
||||
<strong>Bookmarked</strong> item will appear in the top menu bar.
|
||||
<em>(The application usually does not replace the menu bar; clicking the
|
||||
<strong>Feed Reader Central</strong> link will reload it.)</em>
|
||||
<li>Below the title, the source, published date, and updated date (if applicable) are displayed.
|
||||
<li>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.
|
||||
<em>(Web devs, if you have any ideas on how to constrain those as well, I'm all ears…)</em>
|
||||
<li>Below the text, there are three buttons. <strong>Done</strong> leaves the item marked as having been read,
|
||||
<strong>Keep as New</strong> will mark the item as unread, and <strong>Delete</strong> 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.
|
||||
</ul>
|
||||
<h2>Viewing Items for All Feeds</h2>
|
||||
<p>There are three different ways to view items across all your subscriptions.
|
||||
<h3>Unread Items</h3>
|
||||
<p>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.
|
||||
<h3>Bookmarked Items</h3>
|
||||
<p>If you have any bookmarked items, the <strong>Bookmarked</strong> 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.
|
||||
<h3>Searching for Items</h3>
|
||||
<p>The <strong>Search</strong> 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.
|
||||
<p>Under the hood, this uses
|
||||
<a href=https://www.sqlite.org/fts5.html#full_text_query_syntax target=_blank rel=noopener>SQLite’s FTS5</a>,
|
||||
so it is case-insensitive by default and provides some interesting ways to query your items.
|
||||
<ul>
|
||||
<li><code>election</code> would return items with the word “election” in them.
|
||||
<li><code>senat*</code> would return items with words like “Senator”, “senatorial”, or
|
||||
“Senate” in them.
|
||||
<li><code>"election 2024"</code> <em>(note the quotes)</em> would return items that have the phrase
|
||||
“Election 2024” in them; <code>election 2024</code> would return items that have either
|
||||
“election” <em>or</em> “2024” in them.
|
||||
<li><code>election AND 2024</code> is the same as above; <code>AND</code> requires that both conditions be
|
||||
satisfied. (<code>OR</code> is also supported; both these must be uppercase.)
|
||||
<li><code>election NOT president*</code> would return items containing “election”, but only if they
|
||||
did <em>not</em> have words like “president” or “presidential”.
|
||||
</ul>
|
||||
<h2>Viewing Items by Feed</h2>
|
||||
<p>Other than the unread and bookmarked links mentioned above, lists of items by feed are linked on the
|
||||
<strong>Feeds</strong> page. Below each feed’s title, there are links for <strong>All</strong>,
|
||||
<strong>Unread</strong>, and <strong>Bookmarked</strong>, along with a count of items that fit the status.
|
||||
(If there are no items, the word is not linked.)
|
||||
<h2>A Note on Sorting</h2>
|
||||
<p>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.
|
||||
</article><?php
|
||||
page_foot();
|
||||
$db->close();
|
||||
Loading…
Reference in New Issue
Block a user