WIP on docs (#1)

src/public/docs/feeds.php

@@ -0,0 +1,74 @@
+<?php
+include '../../start.php';
+
+$db = Data::getConnection();
+Security::verifyUser($db, redirectIfAnonymous: false);
+
+page_head('Feeds | Documentation'); ?>
+<h1>Feeds</h1>
+<p class=back-link><?=hx_get('./', '&lang;&lang; Documentation Home')?>
+<article class=docs>
+    <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 &ldquo;link&rdquo;)">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&rsquo;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&rsquo;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&rsquo;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 &ldquo;Your Unread Items&rdquo; 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
+        shell script to provide some environment settings, then telling <code>cron</code> to run that script.
+    <pre class=item_content>
+#!/bin/bash
+exec 1> >(logger -t feed-reader-central) 2>&1
+cd /path/to/frc
+php-cli util/refresh.php all</pre>
+    <p>Save this (<code>frc-refresh.sh</code> might be a good name) and be sure it is executable
+        (<code>chmod +x ./frc-refresh.sh</code>). Before we put it in crontab, though, let&rsquo;s understand what each
+        line does:
+    <ul>
+        <li>Line 1 tells the operating system to use the <code>bash</code> shell.
+        <li>Line 2 directs all output to the system log (<code>/var/log/syslog</code>), labeling each entry with
+            <code>feed-reader-central</code>. This lets you review the output for its runs in a log that is already
+            maintained and rotated by the operating system.
+        <li>Line 3 changes the current directory to the one where Feed Reader Central is installed; modify it for where
+            you have installed it. Since we are setting up for a <a href=./the-cli>CLI execution</a>, this should place
+            us one directory up from <code>/public</code>.
+        <li>Line 4 executes the refresh script.
+    </ul>
+    <p>Finally, we are ready to add this to our crontab. Enter <code>crontab -e</code> to edit the file, then add a row
+        at the bottom that looks like this:
+    <pre class=item_content>
+0 */6 * * *  /path/to/job/frc-refresh.sh</pre>
+    <p>The items before the path specify when it should run. This example will run at the top of the hour every six
+        hours. Crontab schedules can be tricky to create; a full treatment is outside the scope of this documentation.
+        However, <a href=https://crontab.guru/#0_*/6_*_*_* target=_blank rel=noopener title="Crontab.guru">this site</a>
+        lets you put values in each position and it translates that to words; this lets you see if what you put is what
+        you meant.
+    <p>This should not require many resources; the majority of its time will be spent waiting for the websites to return
+        their feeds so it can process them. However, if you want it to yield to everything else happening on the server,
+        add <code>nice -n 1</code> (with a trailing space) before the path to the script.
+</article><?php
+page_foot();
+$db->close();