[README] Improved READMEs

2 files changed, 48 insertions, 44 deletions

diff --git a/README.md b/README.md
index c12a347..0d2da8a 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,30 @@
 # syndamiadotcom
 
-Repository for my website. 
+Repository for my website.
+Pages are written in Markdown, converted to HTML with [ssg](https://www.romanzolotarev.com/ssg.html) and [lowdown](https://kristaps.bsd.lv/lowdown/), and edited with AWK scripts.
+Currently, all content is static.
 
-The pages of the website are (mostly) written in Markdown. Using [ssg](https://www.romanzolotarev.com/ssg.html) and [lowdown](https://kristaps.bsd.lv/lowdown/) they are generated into a **static** website.
+For more information on how it works, refer to [S.S. Law](https://syndamia.gitlab.io/ss-law/).
 
-## Contents of this repository
+## Layout and personal setup
 
-The `src` folder contains all of the website files, i.e. the pages, fonts, styles, images, etc.
-
-`install-ssg6-lowdown.sh` is a shell script that installs both ssg and lowdown.
-
-`generate.sh` is a shell script that automatically generates the website into a folder named "website".
-
-## About index.md files
-
-In a lot of folder, the `index.md` files are just hard links of other files! For example, `src/about/index.md` is a hard link to `src/about.html`. Why? Because this way, web links are a lot shorter:
-```
-Old style link -> New style link
-
-syndamia.com/about.html -> syndamia.com/about
-syndamia.com/tutorials/how-to-use-jira/introduction.html -> syndamia.com/tutorials/how-to-use-jira/
-```
-Of course, the old style links are still available, but the website itself won't be using them during navigation.
-
-### List of hard links
-
-In all **multi-page** articles (be it blog article or tutorial or etc.), `introduction.md` is the first page and `index.md` is a hard link to it. Single page articles are just titled `index.md` (it's not a hard link).
-
-|File at|Hard links to|
-|---|---|
-|`about/index.md`|`about.md`|
-|`blog/index.md`|`blog.md`|
-|`contact/index.md`|`contact.md`|
-|`courses/index.md`|`courses.md`|
-|`tutorials/index.md`|`tutorials.md`|
-
-*All links are relative to the src folder!*
+- `.hooks`: Scripts which are executed before git commit.
+  + `pre-commit.sh`: Most (blog, tutorial, ...) pages are accessed without the ending `.html`, which is done by moving the contents of `page.html` to `page/index.html`.
+    I would still like for certain pages to be accessible also with `page.html`, so I create a hardlink from one to the other.
+    However, git (when pulling) removes the appropriate hardlink and the files aren't "synced", this script brings back those hardlinks.
+- `awk-edits`: After HTML generation of pages, AWK scripts do modifications.
+  For more information, read `awk-edits/README.md`.
+- `src`: All website content
+- `generate.sh`: Generates the whole website.
+  + You can give it arguments:
+    + With no argument, the website is created in a "production" way.
+    + With the `dev` parameter (`./generate.sh dev`), you'll get duration information for different stuff.
+    + With the `devs` argument, you'll get duration information, but AWK scripts will be ran individually, rather than being combined (useful for individual performance evaluation; name comes from dev + separated)
+  + There are some variables which handle how the script works:
+    + `REPO_FOLDER`: specifies where the repository is, useful if you want to run the script outside of the repo.
+      awk-edits and src folders are always relative to the repo folder.
+    + `GEN_FOLDER`: folder in which to put the final generated webpages
+    + `GEN_TINY_FOLDER`: folder in which to put the webpages, that have removed features for better accessibility
+    + `AWK_FILE`: where to put the temporary AWK script, which is created by combining all awk-edits scripts into one.
+      Obviously doesn't do anything with `devs` parameter.
+- `install-ssg-lowdown.sh`: Installs ssg and lowdown on the current system.
diff --git a/awk-edits/README.md b/awk-edits/README.md
index 5ff6792..fd1b713 100644
--- a/awk-edits/README.md
+++ b/awk-edits/README.md
@@ -1,20 +1,29 @@
-All `.awk` files in this folder are ran by `generate.sh` and `generate-dev.sh`, after ssg and lowdown have created all HTML pages. These files are meant to work on the resultant HTML.
+These AWK scripts are part of the 3rd "stage" in `generate.sh`, they edit the generated (by ssg and lowdown) HTML pages.
+This allows for custom Markdown syntax and special formatting, for more info, read about [SS-Law](https://syndamia.gitlab.io/ss-law).
 
-For improved efficiency, rather than running every script seperately, they are meant to be concatinated into one script (`generate.sh` and `generate-dev.sh` combine them in `/tmp/syndamiadotcom-awk`), which is ran for each HTML file.
-This forces us to work with the following constraints:
+Without the `devs` argument, `generate.sh` concatenates all of them into one big file, where the order is dependant on the first character of the filename: at the top are those starting with "#", then those with capital letter and finally those with a lowercase letter (however there is no order between files with the same type of starting character).
 
-- NO awk script should print the current line (print should only be used to add new lines)  
-  The script that starts with '\_' contains the print of the current line, all scripts that start with a capital letter are ran before it and all with small letter - after.
-  + If we print the current line in every script, the concatenated will print the current line multiple times
-- Variable names between scripts must be unique
-- `exit` mustn't be used!
-  Instead, use a variable and then add a check to every relevant rule.
+For this reason:
+
+- Files, starting with "#" are "libraries", just AWK scripts that contain only functions
+- Files, starting with a capital letter, are (their code) executed before the line printing (more on that in a bit)
+- Files, starting with a lower case letter, are (their code) executed after the line printing
+
+This is why the following constraints have to be considered:
+
+- If every script printed `$0`, then every line would be duplicated multiple times.
+  That is why you **mustn't** print the current line in your own script, `generate.sh` passes the appropriate AWK code.
+  If you don't want the line to be printed, do `$0 = 0`.
+- Variable names between scripts must be unique, because when combined, unexpected behaviour might occur.
+- `exit` **mustn't** be used!
+  Instead, use a variable and then add a check in the "pattern" part for every rule where you would want to exit.
 
 ## ftags
 
-ftags are strings/words in the Markdown source files, that start with "&&" and continue with any (valid) sequence of characters. The name initially stood for "file tags", since I got the idea while making the file lists functionality. Now I like to think of them as "format tags", since they are used for so much more.
+ftags are strings/words in the Markdown source files, that start with "&&" and continue with any (valid) sequence of characters.
+AWK scripts replace ftags with corresponding HTML.
 
-On the "backend", they just get replaced with specific HTML. List of scripts that handle ftags:
+List of scripts that handle ftags:
 
 |Script|ftags|
 |---|---|
@@ -23,3 +32,6 @@ On the "backend", they just get replaced with specific HTML. List of scripts tha
 |`Presentation.awk`|`&&presentation`, `&&slide`, `&&/slide`, `&&clide`, `&&/clide`, `&&table`, `&&ftable`, `&&tarow`, `&&/table`, `&&linebN` *(N is one of 1, 2, ..., 9)*, `&&fontSIZE` *(SIZE is one of `18`, `20`, `22`, `25`, `27`, `35`)*, `&&/font`, `&&centered`, `&&/centered`, `&&fright`, `&&/fright`, `&&cont`, `&&/cont`|
 
 Information regarding their usage can be found at the top of their respective script file.
+
+The name initially stood for "file tags", since I got the idea while making the file lists functionality.
+Now I like to think of them as "format tags", since they are used for so much more.