Adding info about Video files. Adding docs for multiple external usb drives.

docs/index.md

@@ -2,6 +2,17 @@
 
 Here you will find information about WROLPi, it's modules and how to repair your WROLPi.
 
+## WROLPi
+
+Information about a WROLPi system.
+
+* [Getting Started](system/getting-started.md)
+* [Getting Help](system/getting-help.md)
+* [Logs](system/logs.md)
+* [Systems](system/index.md)
+* [Recommended Hardware](system/recommended-hardware.md)
+* [External USB Drives](system/external-drives.md)
+
 ## Modules
 
 Information about the parts of the WROLPi interface.
@@ -12,16 +23,6 @@ Information about the parts of the WROLPi interface.
 * [Map](modules/map/index.md)
 * [Zim](modules/zim/index.md)
 
-## WROLPi
-
-Information about a WROLPi system.
-
-* [Getting Started](system/getting-started.md)
-* [Getting Help](system/getting-help.md)
-* [Logs](system/logs.md)
-* [Systems](system/index.md)
-* [Recommended Hardware](system/recommended-hardware.md)
-
 ## Guiding Principals
 
 Principals that influence the design decisions of WROLPi.

docs/modules/archives/files.md

@@ -27,11 +27,11 @@ Archive files are named using three parts:
 If archiving `https://wrolpi.org/getting-started`, the resulting files might be named as follows:
 
 ```
-wrolpi.org/2023-01-01-12-00-00_Getting Started.html
+/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.html
-wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.html
+/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.html
-wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.txt
+/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.txt
-wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.json
+/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.readability.json
-wrolpi.org/2023-01-01-12-00-00_Getting Started.png
+/media/wrolpi/archive/wrolpi.org/2023-01-01-12-00-00_Getting Started.png
 ```
 
 WROLPi will attempt to extract the Readability and create a screenshot from the Singlefile. If this is not possible,

docs/modules/map/index.md

@@ -31,22 +31,30 @@ save them to the `map` directory. After they have been downloaded, you will need
 
 You can manually import a PBF file using the **import_map.sh** script:
 
-`/opt/wrolpi/scripts/import_map.sh /media/wrolpi/map/austria-231121.osm.pbf`
+```shell
+/opt/wrolpi/scripts/import_map.sh /media/wrolpi/map/austria-231121.osm.pbf
+```
 
 Multiple maps can be imported like so:
 
-`/opt/wrolpi/scripts/import_map.sh /media/wrolpi/map/one.osm.pbf /media/wrolpi/map/two.osm.pbf /media/wrolpi/map/three.osm.pbf`
+```shell
+/opt/wrolpi/scripts/import_map.sh /media/wrolpi/map/one.osm.pbf /media/wrolpi/map/two.osm.pbf /media/wrolpi/map/three.osm.pbf
+```
 
 ## Reset Map
 
 If your map is not working, maps cannot be imported, or some other reason, you can reset the map database using the
 reset script:
 
-`/opt/wrolpi/scripts/reset_map.sh`
+```shell
+/opt/wrolpi/scripts/reset_map.sh
+```
 
 Next, run the repair script:
 
-`/opt/wrolpi/repair.sh`
+```shell
+/opt/wrolpi/repair.sh
+```
 
-Browse to your map, you should see the default map. If you do not, you may need to clear your browse's cache. Next,
+Browse to your map, you should see the default map. If you do not, you may need to clear your browse's cache. Finally,
 import your desired maps.

docs/modules/videos/files.md

@@ -0,0 +1,37 @@
+# Video Files
+
+WROLPi creates several files when downloading a video:
+
+1. A video file.
+2. Caption files. The suffix may be prefixed with the language like so: `.en.vtt` or `.es.vtt`
+3. An "info" json file. This file contains large amounts of information about the video: Channel name, Source ID,
+   comments, Like count, etc.
+4. A poster file (thumbnail).
+
+These files all share the same filename but have different suffixes.
+
+| File Suffix | Purpose                      |
+|-------------|------------------------------|
+| .mp4        | The video.                   |
+| .vtt        | The captions.                |
+| .info.json  | Information about the video. |
+| .jpg        | The poster (thumbnail).      |
+
+Video files are named using three parts:
+
+1. The Channel Name.
+2. The Published Date (upload date).
+3. The Source ID (a unique string of characters linking to the video, i.e `0xfMLNVFq2Y`)
+4. The title of the video.
+
+The above order is important, it allows the videos to be viewed chronologically in the file browser. The Source ID
+is important because it prevents a conflict if a Channel uploads a video with the same name on the same day.
+
+Example file names for a video:
+
+```
+/media/videos/wrolpi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi v0.11 beta demo.mp4
+/media/videos/wrolpi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi v0.11 beta demo.en.vtt
+/media/videos/wrolpi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi v0.11 beta demo.info.json
+/media/videos/wrolpi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi v0.11 beta demo.jpg
+```

docs/modules/videos/index.md

@@ -8,6 +8,8 @@ Videos Module (`/videos`) allows browsing all video files.
 In the context of WROLPi, a Video refers to a set of [similarly named files](files.md) created during
 download. A single video file is also supported.
 
+![video-page.png](video-page.png)
+
 ## Video Format
 
 As of the writing of this article, WROLPi favors MP4 files due to their small size and universal support.
@@ -67,4 +69,19 @@ When the indexes for a Video are generated for searching, they are searched in t
 
 1. Title
 2. Description
-3. Subtitles
+3. Subtitles
+
+## Videos without WROLPi
+
+WROLPi comes with VLC pre-installed, this application allows you to watch video files, even if the React App is not
+working. VLC also displays captions when the caption file is named like the video file (see
+[Video Files](../videos/files.md)).
+
+### Raspberry Pi
+
+VLC can be launched by navigating: `Applicaions Menu > Sound & Video > VLC Media Player`
+
+![wrolpi-launch-vlc.png](wrolpi-launch-vlc.png)
+
+Any video file can be opened by navigating `Media > Open File`. VLC will automatically display captions files that
+WROLPi has downloaded.

docs/modules/zim/index.md

@@ -28,4 +28,18 @@ WROLPi will search any Zim file found in the `zims` directory, but not every pro
 subscription list. If you would like to download a specific Zim file, use the **Files Downloader** and save the file to
 the `zims` directory.  (You may need to restart your WROLPi for the new Zim file to be found.)
 
-![Downloading a Zim file using the Files Downloader](zim-file-downloader.png)
+![Downloading a Zim file using the Files Downloader](zim-file-downloader.png)
+
+## Kiwix without WROLPi
+
+WROLPi comes with Kiwix pre-installed, this application allows you to use your zim files even if the React App is not
+working.
+
+### Raspberry Pi
+
+Kiwix can be started by navigating: `Applications Menu > Education > Kiwix`
+
+![kiwix-rpi-application-start.png](kiwix-rpi-application-start.png)
+
+Any zim file can be opened using the "Open" button on the top right of the Kiwix application. Zim files are usually
+stored in `/media/wrolpi/zims`.

docs/other/ebooks.md

@@ -3,7 +3,13 @@
 eBooks are a secondary file type in WROLPi, which means that they do not yet have a dedicated module, and some features
 may not yet be available.
 
-Epub files are desired as ebooks, though some support for Mobi files is provided.
+Epub files are desired as ebooks, though some support for Mobi files is provided. Reasons why WROLPi supports Epub:
+
+* Epub files are simple.  An Epub file is a zip file containing HTML files.
+* Third-party support for reading Epubs is much more feature-rich.
+* Images are files in the Epub zip.
+* Device supports for Epubs is nearly ubiquitous.
+* Because an Epub contains HTML files, it makes it easy to display them in a web browser.
 
 ## Searching
 

docs/system/external-drives.md

@@ -0,0 +1,45 @@
+# External USB Drive Configuration
+
+WROLPi expects a single USB drive to be mounted at `/media/wrolpi`. However, multiple drives are supported. WROLPi
+uses special directories to know where to place downloaded files. The config special directories cannot be changed
+and WROLPi will always look for it at `/media/wrolpi/config`
+
+The default special directories are the following (the inputs are disabled because the "Edit Directories" toggle
+is not checked):
+
+![Special Directories Settings](special-directories-settings.png)
+
+## 2+ drives
+
+As of the writing of this article, WROLPi partially supports multiple drives. The _primary_ drive must be mounted to
+`/media/wrolpi`, the configs will be written to this drive. The other drive must be mounted within `/media/wrolpi`.
+
+If you wanted your _secondary_ drive named "secondary", you could mount it at `/media/wrolpi/secondary`. Linux will
+ensure the files are placed in the correct drives.
+
+### Migrating from one to two drives
+
+Assuming that you have a WROLPi with a single external hard drive, and would like to add a second drive, follow these
+steps.
+
+1. Mount the _secondary_ drive to some path in `/media/wrolpi`. We will assume you use `/media/wrolpi/secondary` for
+   this example. Follow this pattern for all new drives.
+    1. `mkdir /media/wrolpi/secondary`
+    2. `mount /dev/sdb1 /media/wrolpi/secondary`
+2. Decide where WROLPi will download files.
+    1. WROLPi will download videos to `/media/wrolpi/videos` by default. If you want WROLPi to save new videos to
+       the secondary drive, edit the "Videos Directory" in `Admin > Settings > Special Directories` to something like
+       `secondary/videos`.
+    2. Do this for all special directories.
+    3. You can keep all special directories in the _primary_ drive, WROLPi will still search the _secondary_ drive for
+       any new files.
+3. Make the drive mounts permanent by modifying `/etc/fstab`:
+
+    ```
+    /dev/sda1 /media/wrolpi auto defaults,nofail 0 0           # primary
+    /dev/sdb /media/wrolpi/secondary auto defaults,nofail 0 0  # secondary
+    ```
+
+4. Verify that the mounts are correct by rebooting.
+    - `sudo reboot`
+5. [Refresh your files](../modules/files/index.md#refreshing)

docs/system/getting-started.md

@@ -4,13 +4,15 @@
 
 To finish your WROLPi installation follow these steps:
 
-1. Modify fstab to mount your external drive. In the example below, `/dev/sda1` will be mounted to `/media/wrolpi`
+1. Modify fstab to mount your external drive(s). In the example below, `/dev/sda1` will be mounted to `/media/wrolpi`
     1. `echo '/dev/sda1 /media/wrolpi auto defaults,nofail 0 0' | sudo tee -a /etc/fstab`
 2. Finish the installation with the repair script: `sudo bash /opt/wrolpi/repair.sh`
 3. Reboot: `sudo reboot`
 4. After reboot, browse to `http://wrolpi.local` or `http://127.0.0.1` on the WROLPi itself.
 5. [Refresh your files](../modules/files/index.md#refreshing)
 
+[Support for multiple drives](external-drives.md)
+
 # Creating a new WROLPi
 
 ## Raspberry Pi

docs/system/logs.md

@@ -5,15 +5,21 @@ gathered by `systemd`.  Logs are viewed using `journalctl`.
 
 You can watch all the logs on your WROLPi:
 
-`journalctl -f`
+```shell
+journalctl -f
+```
 
 More detailed logs can be viewed:
 
-`journalctl -f -p debug`
+```shell
+journalctl -f -p debug
+```
 
 To view logs only from the most recent boot:
 
-`journalctl -f -b`
+```shell
+journalctl -f -b
+```
 
 The above commands use `-f` (follow) which will display logs as soon as they are created.  You can view older logs by
 removing `-f` from the command, but you will need to use your keyboard to navigate the logs.  Use `up`, `down`,
@@ -24,22 +30,30 @@ the bottom of the logs.
 
 To watch the API logs:
 
-`journalctl -f -u wrolpi-api`
+```shell
+journalctl -f -u wrolpi-api
+```
 
 ## React App
 
 To watch the React App logs:
 
-`journalctl -f -u wrolpi-app`
+```shell
+journalctl -f -u wrolpi-app
+```
 
 ## Map
 
 To watch the Map logs:
 
-`journalctl -f -u renderd`
+```shell
+journalctl -f -u renderd
+```
 
 ## Zim
 
 To watch the React App logs:
 
-`journalctl -f -u wrolpi-kiwix`
+```shell
+journalctl -f -u wrolpi-kiwix
+```

docs/system/primary-secondary-tertiary.md

@@ -3,10 +3,11 @@
 WROLPi attempts to integrate all services in an easy to learn interface. But, if the React app is unavailable, secondary
 and tertiary options to use your WROLPi may be available.
 
-| Module   | Primary   | Secondary                                               | Tertiary                                            |
+| Module   | Primary                                   | Secondary                                                                      | Tertiary                                                          |
-|----------|-----------|---------------------------------------------------------|-----------------------------------------------------|
+|----------|-------------------------------------------|--------------------------------------------------------------------------------|-------------------------------------------------------------------|
-| Videos   | React App | Open video files with VLC.                              | Open subtitle files with a text editor.             |
+| Videos   | [React App](../modules/videos/index.md)   | [Open video files with VLC.](../modules/videos/index.md#videos-without-wrolpi) | Open subtitle files with a text editor.                           |
-| Archives | React App | Open Archive files directly with Chromium               | Readability files can be opened with a text editor. |
+| Archives | [React App](../modules/archives/index.md) | Open Archive files directly with Chromium                                      | Readability files can be opened with a text editor.               |
-| Map      | React App | Map is directly accessible on port `:8084`              | None                                                |
+| Map      | [React App](../modules/map/index.md)      | Map is directly accessible on port `:8084`                                     | None                                                              |
-| Zim      | React App | Kiwix server is directly accessible on port `:8085`     | Kiwix application                                   |
+| Zim      | [React App](../modules/zim/index.md)      | Kiwix server is directly accessible on port `:8085`                            | [Kiwix application](../modules/zim/index.md#kiwix-without-wrolpi) |
-| Help     | React App | Markdown files are available in `/opt/wrolpi-help/docs` | None                                                |
+| Help     | [React App](../..)                        | Markdown files are available in `/opt/wrolpi-help/docs`                        | None                                                              |
+

docs/system/systemd.md

@@ -1,10 +1,12 @@
 # Service Control
 
+WROLPi services are controlled by `systemd`.
+
 You can view and control the WROLPi services using these commands:
 
-| Service   | Status                          | Logs                      | Restart                          | Stop                          | Start                          |
+| Service   | Status                          | Logs                         | Restart                          | Stop                          | Start                          |
-|-----------|---------------------------------|---------------------------|----------------------------------|-------------------------------|--------------------------------|
+|-----------|---------------------------------|------------------------------|----------------------------------|-------------------------------|--------------------------------|
-| API       | `systemctl status wrolpi-api`   | `journalctl wrolpi-api`   | `systemctl restart wrolpi-api`   | `systemctl stop wrolpi-api`   | `systemctl start wrolpi-api`   |
+| API       | `systemctl status wrolpi-api`   | `journalctl -u wrolpi-api`   | `systemctl restart wrolpi-api`   | `systemctl stop wrolpi-api`   | `systemctl start wrolpi-api`   |
-| React App | `systemctl status wrolpi-app`   | `journalctl wrolpi-app`   | `systemctl restart wrolpi-app`   | `systemctl stop wrolpi-app`   | `systemctl start wrolpi-app`   |
+| React App | `systemctl status wrolpi-app`   | `journalctl -u wrolpi-app`   | `systemctl restart wrolpi-app`   | `systemctl stop wrolpi-app`   | `systemctl start wrolpi-app`   |
-| Map       | `systemctl status renderd`      | `journalctl renderd`      | `systemctl restart renderd`      | `systemctl stop renderd`      | `systemctl start renderd`      |
+| Map       | `systemctl status renderd`      | `journalctl -u renderd`      | `systemctl restart renderd`      | `systemctl stop renderd`      | `systemctl start renderd`      |
-| Zim       | `systemctl status wrolpi-kiwix` | `journalctl wrolpi-kiwix` | `systemctl restart wrolpi-kiwix` | `systemctl stop wrolpi-kiwix` | `systemctl start wrolpi-kiwix` |
+| Zim       | `systemctl status wrolpi-kiwix` | `journalctl -u wrolpi-kiwix` | `systemctl restart wrolpi-kiwix` | `systemctl stop wrolpi-kiwix` | `systemctl start wrolpi-kiwix` |