WIP on docs (#1)
This commit is contained in:
parent
da34f36530
commit
1b65694e05
|
|
@ -4,15 +4,37 @@ include '../../start.php';
|
||||||
$db = Data::getConnection();
|
$db = Data::getConnection();
|
||||||
Security::verifyUser($db, redirectIfAnonymous: false);
|
Security::verifyUser($db, redirectIfAnonymous: false);
|
||||||
|
|
||||||
page_head('Refresh Feeds | Documentation'); ?>
|
page_head('Feeds | Documentation'); ?>
|
||||||
<h1>Refresh Feeds</h1>
|
<h1>Feeds</h1>
|
||||||
<p class=back-link><?=hx_get('./', '⟨⟨ Documentation Home')?>
|
<p class=back-link><?=hx_get('./', '⟨⟨ Documentation Home')?>
|
||||||
<article class=docs>
|
<article class=docs>
|
||||||
<h2>Manual Feed Refresh</h2>
|
<h2>Adding a Feed</h2>
|
||||||
<p>Next to the “Your Unread Items” heading on the main page, there is a link labeled “Refresh All
|
<p>On the top menu bar, click the <strong>Feeds</strong> link, then click the <strong>Add Feed</strong> button. In
|
||||||
Feeds”. Clicking this link will reload the main page once the feeds have been refreshed. Depending on the
|
the field that is displayed, enter the
|
||||||
number and size of feeds, this may take a bit of time; each feed is refreshed individually.
|
<abbr title="Uniform Resource Locator (aka “link”)">URL</abbr> for the feed. Then click the
|
||||||
<h2>Automatic Refreshing</h2>
|
<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
|
<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
|
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
|
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'); ?>
|
page_head('Documentation'); ?>
|
||||||
<h1>Documentation Home</h1>
|
<h1>Documentation Home</h1>
|
||||||
<article>
|
<article>
|
||||||
<p><?=hx_get('./the-cli', 'About the CLI')?> provides orientation on Feed Reader Central’s command line
|
<h2>About the Application</h2>
|
||||||
interface
|
<p>This application is designed to be a lightweight, near-zero dependency application that individuals can run
|
||||||
<p><?=hx_get('./security-modes', 'Configuring Security Modes')?> describes the three security modes and how to
|
themselves. The idea that let to its creation was a desire to have a set of
|
||||||
manage each of them
|
<abbr title="Really Simple Syndication">RSS</abbr> feeds which could be read from multiple devices on the same
|
||||||
<p><?=hx_get('./refresh-feeds', 'Refresh Feeds')?> has instructions on how feeds can be refreshed on a schedule
|
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
|
</article><?php
|
||||||
page_foot();
|
page_foot();
|
||||||
$db->close();
|
$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