Merge pull request #52 from chrizzo-hb/main

Minor improvements to FAQ and patches section

Author: chrizzo-hb

docs/configure/patches-and-overlays.md

@@ -21,17 +21,17 @@ If you are a Windows user who has never worked with Linux before, you might want
 
 ### File systems on Windows machines
 
-On your Windows computer, each **drive** (or **partition**) has an assigned **drive letter**. You might think about them like labeled drawers of a filing cabinet. The **main drive** that hosts your Windows installation traditionally uses the drive letter `C:` - this is a relic of a time when drive letters `A:` and `B:` where reserved for the two floppy disc drives computers used to have. However, if you connect another drive to your PC, like a thumb drive or a SD card, Windows automatically assigns new drive letters to them, so you can access those drives from your *Windows Explorer*. Files and folders are addressed by their **absolute path** which starts with the **drive letter**. E.g., the folder which holds your pictures is located at
+On your Windows computer, each **drive** (or **partition**) has an assigned **drive letter**. You might think about them like labeled drawers of a filing cabinet. The **main drive** that hosts your Windows installation traditionally uses the drive letter `C:` - this is a relic of a time when drive letters `A:` and `B:` were reserved for the two floppy disk drives computers used to have. However, if you connect another drive to your PC, like a thumb drive or a SD card, Windows automatically assigns new drive letters to them, so you can access those drives from your *Windows Explorer*. Files and folders are addressed by their **absolute path** which starts with the **drive letter**. E.g., the folder which holds your pictures is located at
 
 ```
 C:\Users\<username>\Pictures
 ```
 
 ### File systems on Linux machines 
 
-Linux filesystems work a little different. On Linux, every **drive** is treated like a **folder**. A Linux system always has a so called **root** that **loosely** corresponds conceptually to the drive letter `C:` on a Windows machine. The **root** is always referred to by the symbol `/`. By definition, each **absolute path** always starts with `/` symbol.
+Linux filesystems work a little different. On Linux, every **drive** is treated like a **folder**. A Linux system always has a so called **root** that **loosely** corresponds conceptually to the drive letter `C:` on a Windows machine. The **root** is always referred to by the symbol `/`. By definition, each **absolute path** always starts with the `/` symbol.
 
-Other **drives** are treated like **subfolders** of the **root**. With a command called `mount`, any **empty folder** on a Linux system can be assigned to **any drive** of the device. It is even allowed, to have **more than one folder** that points to **the same drive**. Following the previous metaphor, consider a filing cabinet with only a **single drawer**.
+Other **drives** are treated like **subfolders** of the **root**. With a command called `mount`, any **empty folder** of a Linux system can be assigned to **any drive** of the device. It is even allowed, to have **more than one folder** that points to **the same drive**. Following the previous metaphor, consider a filing cabinet with only a **single drawer**.
 
 For example, on your KNULLI device, your games are stored in
 
@@ -112,7 +112,7 @@ point **to the exact same file**, too.
 
 Since everything outside of the `/userdata` folder of your KNULLI installation is **read-only** by definition, you will need to create an **overlay** to make **permanent** changes to your KNULLI installation. Otherwise, all changes will simply be undone after every reboot of your system.
 
-Your primary SD card (SD1) has a drive called `BATOCERA`, which is formatted to **FAT32** and can be accessed easily from Windows, Linux, and MacOS. On that drive, you will find a folder called `boot` which contains a **file** called `batocera` - that file contains the **majority of your KNULLI installation**. (This is why you can manually update your KNULLI installation by simply replacing this file, as explained in the [Update](../../play/update) section.
+Your primary SD card (SD1) has a drive called `BATOCERA`, which is formatted to **FAT32** and can be accessed easily from Windows, Linux, and MacOS. On that drive, you will find a folder called `boot` which contains a **file** called `batocera` - that file contains the **majority of your KNULLI installation**. (This is why you can manually update your KNULLI installation by simply replacing this file, as explained in the [Update](../../play/update) section.)
 
 The **overlay** is **another** file that is just called `overlay` and resides in the same folder. The overlay is **optional** - usually, users do **not** have an overlay in place. The **overlay file** contains **changes** you made to the KNULLI installation, which will be applied **during boot**.
 
@@ -156,11 +156,50 @@ There are several options to put files in the right places **outside** of the `/
     or
     ```
     mv /userdata/system/some-file.sh /usr/bin/some-file.sh
-    ```    
+    ```
+    where the **first** argument is always the path to the **source file** you want to copy/move and the **second** argument is always the **final destination** where you want the file to end up.    
     
 ### Making files executable
 
-After you have moved the files in the right places, you need to make sure that all files which are **supposed** to be executable **actually are** executable. Again, you have several options to achieve this:
+After you have moved the files in the right places, you need to make sure that all files which are **supposed** to be executable **actually are** executable.
+
+#### Linux file system permissions
+
+On Linux file systems, three different permissions can be set on each file or folder:
+
+* The **read** (`r`) permission allows to **read** the contents of the file.
+* The **write** (`w`)  permission allows to **modify** or even **delete** the file and/or its content.
+* The **execute** (`x`)  permission allows to **execute** the file, which is a special precaution to avoid users accidentally launching dangerous programs. Each program has to be actively set to actually be **executable**.
+
+The three permissions can be set on each file for three different "user classes":
+
+* The **owner** is a **single user** who **owns** the file. (It doesn't necessarily has to be the file's creator.)
+* The **group** is a single **group of users** who might have a certain interest in the file.
+* The **others** are **all other users** who are **not** the owner and **not** members of the group.
+
+As a result, the permissions of each file can be represented by a 3-by-3 matrix. In this example, **everyone** can **read** and **execute** the file, but only the **owner** can **modify** it:
+
+|        | Read                  | Write                 | Execute               |
+| ------ | --------------------- | --------------------- | --------------------- |
+| Owner  | :material-check-bold: | :material-check-bold: | :material-check-bold: |
+| Group  | :material-check-bold: |                       | :material-check-bold: |
+| Others | :material-check-bold: |                       | :material-check-bold: |
+
+This corresponds to a string representation of
+
+```
+rwxr-xr-x
+```
+
+where the first 3 letters represent the **owner**, the next 3 letters represent the **group** and the last 3 letters represent the **others**.
+
+#### Setting Linux file permissions
+
+!!! warning "Make sure that files need to be executable"
+
+    Before you make a file executable, make sure the file actually **needs** to be executable. Do **not** randomly mark files as executable "just to be safe". If you are unsure, check back with the patch developer and ask if a file should be executable or not.
+
+Again, you have several options to set the file permissions on the files of your KNULLI system and make sure a file is **executable**:
 
 * If using WinSCP, you can right-click a file and select *Properties*.
     * In the *Common* tab, go to the *Permissions* section and make sure all the *X*es are **checked** if the file is required to be **executable**.
@@ -173,7 +212,7 @@ After you have moved the files in the right places, you need to make sure that a
     ```
     -rwxr-xr-x 1 root root 458 Aug  3 22:20 /userdata/system/patch-installer.sh
     ```
-    and you can tell from the part `rwxr-xr-x` if a file is executable (you see 3 `x` letters) or not (you see less than 3 or even no `x` letters).
+    and you can tell from the part `rwxr-xr-x` if a file is executable for **everyone**.
     * use the `chmod` command to change the permissions of a file and make it executable, e.g.,
     ```
     chmod +x /userdata/system/patch-installer.sh

docs/faq/knulli.md

@@ -37,7 +37,7 @@ The long answer is: After we adapted Batocera to make it work on the RG35XX Plus
 
 ### Q: Where can I download the latest version?
 
-A: You will find the latest version of KNULLI on our [Releases page](https://github.com/knulli-cfw/distribution/releases/latest). Find the download for your device in the `Installation Package Downloads` section and follow the [Installation guide](../play/install) to install KNULLI on your device. If your device is not listed there, please be patient - there is no public release of KNULLI for your device available, yet.
+A: You will find the latest version of KNULLI on our [Releases page](https://github.com/knulli-cfw/distribution/releases/latest). Find the download for your device in the `Installation Package Downloads` section and follow the [Quick Start Guide](../../play/quick-start) to install KNULLI on your device. If your device is not listed there, please be patient - there is no public release of KNULLI for your device available, yet.
 
 ---
 
@@ -49,12 +49,7 @@ A: You will find a list of all currently supported devices in the `Installation
 
 ### Q: Do I have to flash every release or can I update?
 
-A: For most of the releases you can update:
-  * Download the boot.tar.xz file from the releases page
-  * Extract its content
-  * Mount your KNULLI SDCARD on your PC/Mac/Linux computer
-  * Delete the file ``boot/knulli`` (you can make a backup of this file on your computer in case you want to revert to the previous version)
-  * Copy the contents of the extracted boot.tar.xz to the SDCARD
+A: For most of the releases you can run a manual update as explained in the [Update](../../play/update) section.
 
 ---
 

docs/faq/troubleshooting.md

@@ -11,12 +11,7 @@ Instead of accessing the partition directly, we propose to use network transfer
 
 ### Q: Can I use a second SD card for my roms/bios content?
 
-A: Yes! if you have a new or empty SDCARD you can insert the SDCARD on the second slot of the RG35XX and follow these steps:
-
-* Boot KNULLI and go to ``Settings -> System Settings -> Storage Device`` and change it from ``INTERNAL`` to your second card, e.g. ``SHARE - 25.6G``. 
-* Exit the settings menu and the system will indicate you need to reboot to get the changes applied. 
-* Go to the menu ``Settings -> Quit -> Restart System`` to reboot. The system will reboot and the second card will be now used for batocera and the folder structure (roms, bios, etc.) will be created. 
-* You can now shutdown the console, insert the card on your computer, and copy your bios & roms content.
+A: Yes! Have a look in the [Second SD Card](../../play/add-games/second-sd-card) section!
 
 ---
 
@@ -38,23 +33,15 @@ A: Expanding and booting the first time with a 64GB SDCARD takes about 1 to 1:30
 
 ---
 
-### Q: I've installed KNULLI or updated to the latest version and my controls don't respond as expected - what can I do?
-
-A: For some devices, especially those which share a common installation image (e.g., the RG35XX H/Plus/SP series), it might be required to manually map the controls after the first installation. To do that, follow the instructions in the [Control](../../configure/controls) section.
-
----
-
 ### Q: I cannot connect to my Wi-Fi even though my device has a wireless network adapter - what can I do?
 
 A: Make sure that your router is set to WPA2. Some users experience connection issues with Wi-Fis which are set to WPA3.
 
 ---
 
-### Q: I've installed/updated to the latest version and I don't have audio, or my controls don't respond, or something else is not working as expected:
+### Q: I've installed/updated to the latest version and I don't have audio, or my controls don't respond, or something else is not working as expected - what can I do?
 
-A: If you have updated from an older version you may need to copy the ``batocera.conf`` from the releases page to your SD card:
-  * If you use one single SD card, mount the second partition on your PC/Mac/Linux (``SHARE``) and copy the file to ``system/batocera.conf``
-  * If you use two SD cards, mount the second SD card on your PC/Mac/Linux and copy the file to ``system/batocera.conf``
+A: You might want to try to reset your device to **factory settings**. Please follow our guide on [Resetting to Factory Settings](../../configure/reset-to-factory-settings)
 
 ---
 
@@ -66,7 +53,7 @@ A: Nothing. But don't worry! If you see this message, it only means that your ve
 
 ### Q: Why are bezel decorations not working on my KNULLI device?
 
-A: Most bezel decorations are made for screens with an aspect ratio of 16:9. Consequently, those bezels do not work on a 4:3 display (like on the Anbernic RG35XX H/Plus/SP). To get bezel decorations working, find a bezel pack for 4:3 displays. You will find a detailed explanation (and a pointer to 4:3-compatible bezels) in the [Bezel Decorations](../../configure/bezel-decorations) section.
+A: Most bezel decorations are made for screens with an aspect ratio of 16:9. Consequently, those bezels do not work on a 4:3 display (like on the Anbernic RG35XX H/Plus/SP). To get bezel decorations working, find a bezel pack for 4:3 displays. You will find a detailed explanation (and a pointer to 4:3-compatible bezels) in the [Bezel Decorations](../../configure/customization/bezel-decorations) section.
 
 ---