Fixes in the documentation

docker/README.md

@@ -3,7 +3,7 @@
 ## Using docker-compose
 
 You may build your changes by using the compose file. First create an `.env`
-file in /docker. The contents should be similar to:
+file in /docker. The contents should be similar to that of `.env.example`:
 
 ```text
 HOSTUID=1000
@@ -13,19 +13,23 @@ ENTRYPOINT:$PWD/docker/default-entry.sh
 SOURCE_ROOT=$PWD
 ```
 
-Replace the values for HOSTUID and HOSTGID with your system uid and gid. Then,
-from the source root:
+Replace the values for `HOSTUID` and `HOSTGID` with your system `uid` and `gid`.  
+Then, from the source root:
 
-    docker-compose -f docker/docker-compose.yml run --rm  dev
+```sh
+docker-compose -f docker/docker-compose.yml run --rm  dev
+```
 
 This will start the container and build the app.
 
 To enter the build environment without actually building the app:
 
-    export ENTRYPOINT=$PWD/docker/shell-entry.sh
-    docker-compose -f docker/docker-compose.yml run --rm  dev
+```sh
+export ENTRYPOINT=$PWD/docker/shell-entry.sh
+docker-compose -f docker/docker-compose.yml run --rm  dev
+```
 
-Remember to unset ENTRYPOINT when you wish to use the default again.
+Remember to unset `ENTRYPOINT` when you wish to use the default again.
 
 <!--
 This doesn't work unless the files are "mounted"
@@ -39,8 +43,8 @@ docker run -it --rm -v \
 ```
 -->
 
-All of the above methods will mount your current directory as */workspace*
-inside the container. Your username will be *builder*. By default, you will
+All of the above methods will mount your current directory as _/workspace_
+inside the container. Your username will be _builder_. By default, you will
 not have root privileges (which are not necessary to build and test). However,
 you can use `sudo` if you need to run `apt` or any other commands that require
 root access.
@@ -49,7 +53,7 @@ root access.
 
 In the examples above, we've included `--rm` as an argument. This normally
 removes the container after it's exited. `docker ps -a` displays containers
-that still exist so you may periodically want to make sure you don't have
+that still exist, so you may periodically want to make sure you don't have
 unused or unwanted containers. See the official [Docker docs] for more
 information about working with containers. You may, for example, want to
 "reuse" a container, in which case, simply omit the `--rm`.
@@ -58,20 +62,22 @@ information about working with containers. You may, for example, want to
 
 You can pull the image manually:
 
-    docker pull ghcr.io/karurochori/vs-fltk:build-env
+```sh
+docker pull ghcr.io/karurochori/vs-fltk:build-env
+```
 
 If you use `docker-compose` or `docker run ...` the image will be pulled
 automatically the first time.
 
 ## Running the app from the container
 
 > [!WARNING]
-> Note the following instructions were adapted from instructions generated by
-ChatGPT.  
+> Note the following instructions were adapted from some generated by
+> ChatGPT.  
 > The X11 instructions were tested on Manjaro Linux. Use at your own
-risk.  
+> risk.  
 > Please update these docs if you have any information about accuracy or
-security-related considerations.
+> security-related considerations.
 
 To run an application from a Docker container that requires access to the host
 machine's graphics (such as a GUI application), you'll need to share certain
@@ -84,28 +90,30 @@ necessary devices. Here's a general guide:
 1. **Install dependencies on the host:**
    Make sure you have `xhost` installed, which allows you to control access to
    the X server.
-    ```
-    sudo apt install x11-xserver-utils  # For Ubuntu/Debian
-    sudo pacman -S xorg-xhost  # For Arch-based
-    ```
+
+   ```
+   sudo apt install x11-xserver-utils  # For Ubuntu/Debian
+   sudo pacman -S xorg-xhost  # For Arch-based
+   ```
 
 2. **Allow access to X server:**
    Before running the container, allow Docker to access your X server:
-    ```
-    xhost +local:docker
-    ```
+
+   ```
+   xhost +local:docker
+   ```
 
 3. **Run the container with access to the display:**
    When starting the container, pass the display environment variable
    (`$DISPLAY`) and mount the X11 socket. Instead of *dev" for the last
-   argument of `docker-compose` (see above), use *xgui*, which essentially
+   argument of `docker-compose` (see above), use *xgui\*, which essentially
    adds these three arguments (through the compose configuration):
-    
-    ```sh
-    --env="DISPLAY" \
-    --env="QT_X11_NO_MITSHM=1" \
-    --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw"
-    ```
+
+   ```sh
+   --env="DISPLAY" \
+   --env="QT_X11_NO_MITSHM=1" \
+   --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw"
+   ```
 
    - `--env="DISPLAY"`: Passes the display from the host to the container.
    - `--env="QT_X11_NO_MITSHM=1"`: Some applications may need this to avoid shared memory issues.
@@ -118,12 +126,12 @@ necessary devices. Here's a general guide:
 
 1. **Share the Wayland display:**
    If your system uses Wayland, you need to pass the Wayland display and devices:
-    
-    ```sh
-    --env="WAYLAND_DISPLAY=$WAYLAND_DISPLAY" \
-    --volume="/run/user/$(id -u)/wayland:/run/user/$(id -u)/wayland" \
-    --device=/dev/dri \
-    ```
+
+   ```sh
+   --env="WAYLAND_DISPLAY=$WAYLAND_DISPLAY" \
+   --volume="/run/user/$(id -u)/wayland:/run/user/$(id -u)/wayland" \
+   --device=/dev/dri \
+   ```
 
    - `--env="WAYLAND_DISPLAY=$WAYLAND_DISPLAY"`: Passes the Wayland display variable.
    - `--volume="/run/user/$(id -u)/wayland:/run/user/$(id -u)/wayland"`: Shares the Wayland display socket.
@@ -132,12 +140,11 @@ necessary devices. Here's a general guide:
 ### Additional considerations:
 
 - **GPU access**: If your application requires GPU acceleration (e.g.,
-OpenGL), you may also need to pass through GPU devices to the container. For
-example, with NVIDIA, you can use the NVIDIA Docker runtime:
-    ```
-    --gpus all -it
-    ```
+  OpenGL), you may also need to pass through GPU devices to the container. For
+  example, with NVIDIA, you can use the NVIDIA Docker runtime:
+  `   --gpus all -it
+`
 - **X11 access security**: Allowing Docker to connect to your X server with `xhost +local:docker` is not secure. After you're done, revoke access:
-    ```        
-    xhost -local:docker
-    ```
+  ```
+  xhost -local:docker
+  ```

docs/faq.md

@@ -177,13 +177,18 @@ This strategy was not employed as it makes the loading process much slower for m
 ## Licensing
 
 ### Can I contribute to this project?
-Sure! Please be mindful of two things:
-- Make sure you understand that this project uses different licenses for different parts. You should be ok distributing your contributions under those same (or less restrictive) terms. You will be credited, and you are clearly able to distribute any standalone contribution of your beyond the scope of `vs`.  
-- This project is very early, and your contribution might end up in the crossfire of roadmaps changing and goals shifting. If you want to contribute major features, I would *strongly* recommend to reach out or to publish some form of written proposal. 
+Sure! Please be mindful of few things:
+- Make sure you understand that this project uses different licenses for different parts. 
+- You should be ok with us including your contributions under those same terms. 
+- This project is very early, and your contribution might end up in the crossfire of roadmaps changing and goals shifting. 
+- If you want to contribute major features, I would *strongly* recommend to reach out or to publish some form of written proposal. 
+- You should also accept that the CC Attribution–NoDerivs 4.0 covering most of the project will be relaxed at some point. 
+- You will be credited, at the very least by preserving the git history of the project.
+- You are clearly able to distribute any standalone contribution you made as you wish. It is your code.  
 
 ### What about those parts covered by the no-derivatives clauses?
 Those clauses are just intended to protect this project in its early life, not to prevent people from contributing.  
-If you don't plan to make your own fork to distribute an alternative version of `vs`, that is totally fine!
+If your plan is not to make your own fork and distribute an alternative version of `vs`, we are totally fine with that!
 
 ### Why this strange licence?
 You are strange!  
@@ -193,12 +198,12 @@ Or at the very least, I am trying to make it as hard as legally possible.
 `vs` is extremely opinionated, and with opinions come division.  
 XML or JSON, runtime DOM or not, and of course... data sources or arbitrary fetches in embedded scripts.  
 My reluctance in adopting a less restrictive licence at this stage is well explained in the [gemini's faq](https://geminiprotocol.net/docs/faq.gmi).  
-If I had to explain it more in my own words, let's think about a cost function describing the utility of frameworks like `vs`.   
-There are many local minima in which such frameworks could end up stuck during their development, be it as a necessary but temporary phase or the unfortunate outcome of a short-sighted design.  
-*Vision* is the only thing which allows a project to jump across, or at least get quickly out from the local minima of comfort-food.  
-I am not saying my vision is "right" nor immutable, just that I have few high level objectives for this project, and others might not share the same while being somewhat similar in execution.  
+If I had to explain it more with my own words, let's think about a cost function describing the utility of frameworks like `vs`.   
+There are many local minima in which such frameworks could end up stuck during development, be it as a necessary but temporary phase or as the unfortunate outcome of short-sighted design decisions.  
+A good *vision* is the only thing which allows a project to jump across, or at least get quickly out from the local minima of comfort-food.  
+I am not saying my own is "right" nor immutable, just that I have few high-level objectives for this project that others might not share.  
 Allowing `vs` to be freely forked at this stage comes with the very real risk of me being thrown in a competition I never asked for, unable to provide more than shallow promises on why my intention & my objectives would be "better".  
-As I don't plan on making the development of this project an exercise in demagogy and convincing, I temporarily opted for a licencing model which prevents that.  
+As I don't plan on making the development of this project a painful exercise in demagogy and convincing, I temporarily opted for a licencing model which prevents that.  
 Once this project is robust enough to survive a hostile fork, I would be very glad to relicense it under permissive terms.  
 
 That being said, if you feel something in the direction of the project or the technical solutions proposed are not good, please reach out!  

test/fullstack/example-full/README.md

@@ -0,0 +1,3 @@
+This is the general structure of a full stack test. Naming is important and should be preserved if possible.
+
+TODO: Complete this documentation.