From ce17069ecff22e491e977aed76b800a6bba87ab4 Mon Sep 17 00:00:00 2001
From: ER <eino.rauhala@proton.me>
Date: Wed, 10 May 2023 19:51:40 +0300
Subject: [PATCH] docs: refactor: mv inline docs in autorun.sh Moving most of
 the inline docs in autorun.sh to scripts/README.md. This makes the
 documentation more discoverable and approachable (no need to read source
 code).

This commit also removes redundancies from the inline docs,
clears up some phrasing,
and uses more standard formatting and phrasing such as:
- using `` instead of ""
- calling itself `autorun.sh`
- calling pre and post "execution phases"
---
 scripts/README.md  | 34 +++++++++++++++++++++++++++++--
 scripts/autorun.sh | 51 ----------------------------------------------
 2 files changed, 32 insertions(+), 53 deletions(-)

diff --git a/scripts/README.md b/scripts/README.md
index 6a8f165..0085c67 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -2,8 +2,38 @@
 
 You can add custom scripts to this directory and declare them to be run at build time in the `scripts:` section of `recipe.yml`. Custom scripts can be run at either the `pre:` execution phase right after the custom repositories are added, or at the `post:` phase after all of the automatic build steps.
 
-Your scripts will be given exactly one argument when they are executed, which specifies its precise execution phase (`pre` or `post`). The primary purpose of this argument is to streamline the reuse of scripts for multiple stages.
+Your scripts will be given exactly one argument when they are executed, which specifies its precise execution phase (`pre` or `post`). The primary purpose of this argument is to streamline the reuse of scripts for multiple stages. This behaviour is mirrored both in manually declared scripts and scripts ran by `autorun.sh`.
 
 ## `autorun.sh`
 
-`autorun.sh` is enabled by default and automatically runs all scripts in the folders `scripts/pre/` and `scripts/post/` at the correct execution phases. Manually listed scripts can be combined with `autorun.sh`.
+`autorun.sh` is a script that automatically runs all scripts in the folders `scripts/pre/` and `scripts/post/` at the correct execution phases. It is enabled by default, but you can disable it by removing it from `recipe.yml`. Manually listed scripts can be combined with `autorun.sh`.
+
+There are a few rules, which aim to simplify your script management:
+
+- `autorun.sh` will only execute scripts at the FIRST level within the directory, which
+  means that anything stored in e.g. `scripts/pre/deeperfolder/` will NOT execute.
+  This is intentional, so that you can store libraries and helper scripts
+  within subdirectories.
+- You script directories and the scripts within them can be symlinks, to allow
+  easy reuse of scripts. For example, if you want the same scripts to execute
+  during both the `pre` and `post` stages, you could simply symlink individual
+  scripts or the entire `pre` and `post` directories to each other. However,
+  remember to only use RELATIVE symlinks, to ensure that the links work
+  properly. For example, `ln -s ../pre/foo.sh scripts/post/foo.sh`.
+- All scripts execute in a numerically and alphabetically sorted order, which
+  allows you to easily control the execution order of your scripts. If it's
+  important that they execute in a specific order, then you should give them
+  appropriate names. For example, `05-foo.s` would always execute before
+  another script named `99-bar.sh`. It's recommended to use zero-padded,
+  numerical prefixes when you want to specify the execution order.
+- The manually listed scripts in `recipe.yml` should
+  be stored directly within `scripts/`, or in a custom subdirectory that
+  doesn't match any of the execution phases. For example, you could
+  set the `pre:` section of `recipe.yml` to execute both `autorun.sh`
+  and `fizzwidget/something.sh`, and then place a bunch of auto-executed
+  scripts under `scripts/pre/` for the autorunner. This makes it very simple
+  to reuse common scripts between multiple different `recipe.yml` files,
+  while also having some scripts be specific to different `recipe.yml`s.
+- You can safely specify `autorun.sh` as a script in `recipe.yml`,
+  even if the special directories don't exist or don't contain any
+  scripts. It will gracefully skip the processing if there's nothing to do.
diff --git a/scripts/autorun.sh b/scripts/autorun.sh
index 499ed35..3b9b1c2 100644
--- a/scripts/autorun.sh
+++ b/scripts/autorun.sh
@@ -9,57 +9,6 @@ set -oue pipefail
 # This script simplifies your "recipe.yml" management whenever you simply want
 # to "run everything automatically" based on whatever script files exist on disk.
 #
-# Set any or all of your "recipe.yml" script categories to "autorun.sh", and
-# enjoy the magic! The autorunner will then automatically look up all ".sh"
-# script files within the corresponding "scripts/<script mode>/" directory,
-# executing them all in their correct alphabetical and numerical filename order.
-#
-# For example, if you've assigned "autorun.sh" to the "scripts.pre" category
-# of your "recipe.yml", then it will scan and automatically execute everything
-# in your "scripts/pre/" directory.
-#
-# There are a few rules, which aim to simplify your script management:
-#
-# - It will only execute scripts at the FIRST level within the directory, which
-#   means that anything stored in "scripts/pre/deeperfolder/" will NOT execute.
-#   This is intentional, so that you can store libraries and helper scripts
-#   within subdirectories, to simplify your script organization.
-#
-# - You script directories and the scripts within them can be symlinks, to allow
-#   easy reuse of scripts. For example, if you want the same scripts to execute
-#   during both the "pre" and "post" stages, you could simply symlink individual
-#   scripts or the entire "pre" and "post" directories to each other. However,
-#   remember to only use RELATIVE symlinks, to ensure that the links work
-#   properly. For example, "ln -s ../pre/foo.sh scripts/post/foo.sh".
-#
-# - The scripts will be executed with the name of the current "build execution
-#   phase" as their first and only argument, to allow you to easily reuse scripts
-#   across multiple stages. This is consistent with the "build.sh" behavior.
-#
-# - All scripts execute in a numerically and alphabetically sorted order, which
-#   allows you to easily control the execution order of your scripts. If it's
-#   important that they execute in a specific order, then you should give them
-#   appropriate names. For example, "05-foo.sh" would always execute before
-#   another script named "99-bar.sh". It's recommended to use zero-padded,
-#   numerical prefixes when you want to specify the execution order.
-#
-# - It's possible to mix your "autorun scripts" with your regular "recipe.yml"
-#   scripts. The autorunner will only execute things from the correctly named
-#   sub-directories. And the manually listed "recipe.yml" scripts should simply
-#   be stored directly within "scripts/", or in a custom sub-directory that
-#   doesn't match any of the "script category" names. For example, you could
-#   set the "scripts.pre" category of "recipe.yml" to execute both "autorun.sh"
-#   and "fizzwidget/something.sh", and then place a bunch of auto-executed
-#   scripts under "scripts/pre/" for the autorunner. This makes it very simple
-#   to reuse common scripts between multiple different "recipe.yml" files,
-#   by just placing all commonly shared scripts within auto-runner folders,
-#   and then manually listing a few specific per-"recipe.yml" scripts within
-#   each recipe that needs some extra customizations.
-#
-# - You can safely specify this autorun script as your runner in "recipe.yml",
-#   even if the corresponding directory doesn't exist or doesn't contain any
-#   scripts. It will gracefully skip the processing if there's nothing to do.
-#
 
 # Helper functions.
 yell() { echo "${0}: ${*}"; }