improve docs

manual install: use wget -O to specify download file name remove <details>/<summary> tags: breaks nav add missing forum link
poppadum · Mar 6, 2023 · 9ad7182 · 9ad7182
1 parent 2171e7b
commit 9ad7182
Show file tree

Hide file tree

Showing 8 changed files with 42 additions and 36 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -6,6 +6,6 @@ logs/*                  export-ignore
 scripts/                export-ignore
 tests/                  export-ignore
 
-runTests.sh             export-ignore
+run_tests.sh            export-ignore
 sync_to_pi.sh           export-ignore
 sync_to_pi.sh.exclude   export-ignore
diff --git a/.gitignore b/.gitignore
@@ -22,10 +22,10 @@ artwork/recalbox_logos/
 # personal sync script
 sync_to_pi.sh*
 
-# exclude release archives & generated VERSION file
+# exclude release archives & generated BUILD file
 build/dynquee*.zip
 build/release_HOWTO.md
-VERSION
+BUILD
 
 # misc
 examples/

diff --git a/README.md b/README.md
@@ -116,7 +116,7 @@ If things aren't working, first check the log files in the `logs/` directory:
 
 The logs should provide some clues as to what is wrong.
 
-If you still can't get it working, post on the [Recalbox forum] and I will try to help.
+If you still can't get it working, post on the [Recalbox forum][recalbox-forum-commproj] and I will try to help.
 Please paste your config file and debug log file on [pastebin][pastebin] and provide a link when reporting issues.
 
 ---

diff --git a/artwork/README.md b/artwork/README.md
@@ -7,7 +7,7 @@ These are not my work: credit goes to the original authors mentioned below.
 ## `recalbox-next/`
 Authors: Recalbox Project Team
 
-This is a copy of system logos from the `recalbox-next` theme.
+This directory holds a copy of system logos from the `recalbox-next` theme.
 Run `update.sh` to fetch the latest version from the official gitlab repo
 
 Source: https://gitlab.com/recalbox/recalbox-themes/-/tree/master/themes/recalbox-next
@@ -27,4 +27,4 @@ Sources:
 ## `startup/`
 Authors: Recalbox Project Team, Chris Laird
 
-Example startup image which reuses elements of the Recalbox startup image
+Example startup images which reuse elements of the Recalbox startup image
diff --git a/doc/Running_on_separate_device.md b/doc/Running_on_separate_device.md
@@ -61,8 +61,6 @@ Follow these steps to install *dynquee* using the install script:
 If you prefer to install everything manually, follow these instructions. 
 They assume you are installing *dynquee* on a Raspberry Pi running Raspberry Pi OS, but should apply to any debian-like OS.
 
-<details>
-<summary>Click to expand full instructions:</summary>
 
 ### Install Packages
 Install the required packages with:  
@@ -110,7 +108,7 @@ sudo apt install python3 python3-paho-mqtt fbi ffmpeg
 
 1. Download the *dynquee* release and unzip it:  
      ```sh
-     sudo wget https://github.com/poppadum/dynquee/releases/latest/download/dynquee.zip
+     sudo wget -O dynquee.zip https://github.com/poppadum/dynquee/releases/latest/download/dynquee.zip
      sudo unzip dynquee.zip
      ```
 
@@ -153,7 +151,7 @@ If you've checked the logs and still can't see what's wrong, see the [help secti
 There are various ways to get dynquee to run when the machine starts. \
 Recent releases of Raspberry Pi OS use [systemd][systemd] so that's what I recommend.
 
-1. Copy the `systemd` unit file to the systemd directory, and enable it:
+1. Copy the `systemd` unit file to the systemd directory:
     ```sh
     sudo cp install/dynquee.service /etc/systemd/system/
     ```
@@ -178,8 +176,6 @@ or  add it to `/etc/rc.local`
 
 To test, reboot your marquee machine and check that *dynquee* starts automatically.
 
-</details>
-
 ---
 
 

diff --git a/doc/config.md b/doc/config.md
@@ -4,7 +4,7 @@
 
 ## Contents
 - [Introduction](#introduction)
-- [Emulation Station events](#emulation-station-events)
+- [Emulation Station Events](#emulation-station-events)
 - [Search Rules](#search-rules)
 - [Filename Matching](#filename-matching)
 - [Adding Your Own Images And Videos](#adding-your-own-images-and-videos)
@@ -21,7 +21,7 @@ Most settings can be configured in the config file [`dynquee.ini`](../dynquee.in
 
 For each [Emulation Station event](#emulation-station-events), the config file defines a search precedence rule: an ordered list of search terms indicating where to search for media files.
 
-If no files match a search term *dynquee* moves on to the next term.
+If no files match a search term *dynquee* moves on to the next search term.
 That way you can specify which media files to show in order of priority.
 
 For example, when an arcade game is launched, *dynquee* can:
@@ -32,13 +32,13 @@ For example, when an arcade game is launched, *dynquee* can:
 All media files that match a successful search term are displayed in a random order as a slideshow that loops continuously. How long each image or video is shown can be adjusted in the `[slideshow]` section of the config file.
 
 
-## Emulation Station events
+## Emulation Station Events
 A full list of Emulation Station events can be found in the [Recalbox wiki][wiki-es-events]. They are referred to as *events* or *actions*: the terms are used interchangeably.
 
 The most useful are:
 
-* `systembrowsing`: user is browsing list of systems
-* `gamelistbrowing`: user has selected a system and is browsing list of games
+* `systembrowsing`: user is browsing the list of systems
+* `gamelistbrowing`: user has selected a system and is browsing the list of games
 * `rungame`: user has started a game
 * `endgame`: user has exited a game
 * `sleep`: EmulationStation has entered sleep mode
@@ -68,7 +68,7 @@ e.g.
 will first try to locate media for the rom, publisher and system and show all
 files matching those search terms.
 
-Notes:
+**Notes**:
 1. No search rule is defined for the `endgame` action as Emulation Station
    sends another action (usually `gamelistbrowsing`) immediately after
 1. The `wakeup` action causes *dynquee* to repeat the action that occurred immediately before the `sleep` event
@@ -84,6 +84,10 @@ Media filename matching works as follows:
 1. Names of publishers and genres are converted to lower case and a dot is added to the end
     - e.g. `Data East` becomes `data east.`
 
+1. Recalbox's internal system ID for game systems has a dot added to the end:
+    - e.g. `mame` becomes `mame.`
+    - e.g. `neogeocd` becomes `neogeocd.`
+
 1. Names are then matched against the beginning of media filenames.
     - e.g. a ROM named `Chuckie Egg.zip` would match media files named `Chuckie Egg.*`
     - or a game published by `Bally Midway` would match files named `bally midway.*`
@@ -95,7 +99,7 @@ If for some reason you want to store them somewhere else, change the `media_path
 
 Place your media files in the appropriate subdirectory (look at the included files for examples):
 
-- *game-specific* media go in the appropriate system directory; for example:
+- *game-specific* media go in the appropriate game system directory; for example:
     - for the arcade version of [Defender] with a ROM named `defender.zip`, put your media file in `mame/` and name it `defender.<something>` e.g. `mame/defender.01.png`
     - for the Megadrive version of [Aladdin] with a ROM named `aladdin.zip`, put your media file in `megadrive/` and name it `aladdin.<something>` e.g. `megadrive/aladdin.mp4`
 
@@ -104,12 +108,16 @@ the file name must start with Emulation Station's internal system name (use the
     - e.g. for a [Sinclair ZX Spectrum][spectrum] logo, name the file `zxspectrum.<something>` e.g. `system/zxspectrum.logo.png`
 
 - `publisher/` is for game publisher banners & logos
+    - e.g. for a game published by [Konami][konami], name the file `konami.<something>` e.g. `publisher/konami.01.png`
 
-- `startup/` is for files to show when *dynquee* first starts up e.g. a welcome banner or video
+- `startup/` is for files to show when *dynquee* first starts up e.g. a welcome banner or video.
+    Filename does not matter, but use the appropriate file extension e.g. `startup/welcome.png`
 
-- `generic/` is for media that doesn't belong anywhere else, to be used if no other files match
+- `generic/` is for media that doesn't belong anywhere else, to be used if no other files match.
+    If you have designed custom artwork for your Recalbox, place it here.
+    Filename does not matter, but use the appropriate file extension e.g. `generic/my_games_machine.mkv`
 
-Feel free to delete any of the included media files you don't want, but I recommend you leave `media/default.png` as a file of last resort.
+Feel free to delete any of the included media files you don't want, but I recommend you leave `media/default.png` (or replace it with your own custom image) as a file of last resort.
 
 
 ## File Formats
@@ -120,9 +128,9 @@ I recommend `png` for still images, and `mp4` or `mkv` with the H.264 codec for
 ## Scaling Media
 With default settings, still images are zoomed to fit the marquee screen but keep their original aspect ratio; videos are not resized.
 
-If you want to scale videos to the height of the marquee, a helper script `play_video_scaled.sh` is provided. The comments in the config file explain how to use it. Note that the script uses the `marquee_width` & `marquee_height` settings in the config file to calculate video output size, so change those settings to match your marquee screen. Bear in mind that video scaling can tax the CPU which will leave Recalbox fewer CPU cycles available to run emulators[^cpu-usage].
+If you want to scale videos to the height of the marquee, a helper script [`play_video_scaled.sh`](../play_video_scaled.sh) is provided. The comments in the config file explain how to use it. Note that the script uses the `marquee_width` & `marquee_height` settings in the config file to calculate video output size, so change those settings to match your marquee screen. Bear in mind that video scaling can tax the CPU which will leave Recalbox fewer CPU cycles available to run emulators[^cpu-usage].
 
-[^cpu-usage]: Here is the abbreviated output of `top` when running a scaled video at the same time as the Libretro Mame2003+ emulator on my Pi4 2GB: `ffmpeg` is using ~120% of the four cores:
+[^cpu-usage]: Here is the abbreviated output of `top` when running a scaled video at the same time as the Libretro Mame2003+ emulator on my Pi4 2GB: `ffmpeg` is using ~120% of the 400% available on a four-core CPU:
 
     ```
       PID USER      PR  NI    VIRT    RES  %CPU  %MEM     TIME+ S COMMAND
@@ -152,10 +160,10 @@ For each event the change rule can have one of the following values:
 
 I recommend that the rule for the `sleep` event remain set to `always`.
 Changing the rule for `sleep` may prevent the marquee being
-blanked when Recalbox sleeps and cause burn-in on your marquee screen!
+blanked when Recalbox sleeps and cause [burn-in][screen-burn-in] on your marquee screen!
 
 
-## Starting & Stopping *dynquee* Manually
+## Starting And Stopping *dynquee* Manually
 You can start, stop or restart *dynquee* (for example, to reload a changed config file) by typing:  
 ```sh
 /etc/init.d/S32dynquee start|stop|restart|status
@@ -164,14 +172,16 @@ You can start, stop or restart *dynquee* (for example, to reload a changed confi
 Be aware that if you start *dynquee* when Recalbox is already in the sleep state,
 it will stay on the startup media until Recalbox wakes up.
 If there is only one startup image, that image could be shown for any length of
-time and could cause screen burn-in!
+time and could cause [screen burn-in][screen-burn-in]!
 
 
 <!-- LINKS & IMAGES -->
 [Aladdin]: https://en.wikipedia.org/wiki/Disney's_Aladdin_(Virgin_Games_video_game)
 [Defender]: https://en.wikipedia.org/wiki/Defender_(1981_video_game)
 [fbv]: https://github.com/godspeed1989/fbv
 [ffmpeg]: https://ffmpeg.org/
+[konami]: https://en.wikipedia.org/wiki/Konami
 [project-image]: ../dynquee.png
+[screen-burn-in]: https://en.wikipedia.org/wiki/Screen_burn-in
 [spectrum]: https://en.wikipedia.org/wiki/ZX_Spectrum
-[wiki-es-events]: https://wiki.recalbox.com/en/advanced-usage/scripts-on-emulationstation-events#events
+[wiki-es-events]: https://wiki.recalbox.com/en/advanced-usage/scripts-on-emulationstation-events#events
diff --git a/doc/manual_install.md b/doc/manual_install.md
@@ -7,18 +7,18 @@ If you prefer to install *dynquee* manually, follow these steps.
 1. Log in to recalbox as user `root` either [via ssh][recalbox-ssh] or via the console.
 
 1. Create the *dynquee* directory:  
-    ```
+    ```sh
     mkdir -p /recalbox/share/dynquee
     ```
 
 1. Change to that directory:  
-    ```
+    ```sh
     cd /recalbox/share/dynquee
     ```
 
 1. Download the latest *dynquee* release and unzip it:  
      ```sh
-     wget https://github.com/poppadum/dynquee/releases/latest/download/dynquee.zip
+     wget -O dynquee.zip https://github.com/poppadum/dynquee/releases/latest/download/dynquee.zip
      unzip dynquee.zip
      ```
 

diff --git a/media/README.md b/media/README.md
@@ -2,15 +2,15 @@
 
 ## Included Files
 
-- `default.png`: crop/resize of built-in Recalbox logo
+- `default.png`: image displayed as a last resort if no other media matches; crop/resize of built-in Recalbox logo
 
-- `startup/startup.01.png`: default startup image. Reuses elements of Recalbox startup screen
+- `startup/startup.0[12].png`: default startup images which reuse elements of Recalbox startup screen
 
 - `system/*.png`: system logos and banners. Includes
     - system logos from [`recalbox-next`](https://gitlab.com/recalbox/recalbox-themes/-/tree/master/themes/recalbox-next) theme
     - platform logos from [Dan Patrick's v2 Platform Logos](https://archive.org/details/console-logos-professionally-redrawn-plus-official-versions)
 
-- `publisher/*.png`: publisher logos and banners. Includes
+- `publisher/*.png`: publisher logos and banners; includes
     - platform logos from [Dan Patrick's v2 Platform Logos](https://archive.org/details/console-logos-professionally-redrawn-plus-official-versions)
 
 
@@ -33,7 +33,7 @@ Some useful resources:
 
 - [ProgrettoSnaps marquee images for arcade machines](https://www.progettosnaps.net/marquees/)
 
-- HyperSpin FE
+- HyperSpin FE:
     - [MAME Marquee Artwork](https://hyperspin-fe.com/files/file/13379-mame-marquee-artwork/)
     - [PC Games Marquee Collection](https://hyperspin-fe.com/files/file/19937-pc-games-marquee-collection/)
     - [Sega Megadrive/Genesis Marquee Collection](https://hyperspin-fe.com/files/file/19912-sega-megadrivegenesis-marquee-collection/)
@@ -43,7 +43,7 @@ Some useful resources:
 	- includes some genre logos
 	- [github page](https://github.com/UDb23/rpie-custom)
 
-- Launchbox Forums
+- Launchbox Forums:
     - [Dave's Clear Logos style 2](https://forums.launchbox-app.com/files/file/787-daves-clear-logos-style-2zip/)
     - [Dan Patrick's Platform Logos](https://forums.launchbox-app.com/files/file/3402-v2-platform-logos-professionally-redrawn-official-versions-new-bigbox-defaults/)