[hooks] Updated and reformatted documentation for everything in hooks, including README

6 files changed, 184 insertions, 84 deletions

diff --git a/generate-hooks/README.md b/generate-hooks/README.md
index 52bb4f4..5949be4 100644
--- a/generate-hooks/README.md
+++ b/generate-hooks/README.md
@@ -1,15 +1,15 @@
-These scripts are ran by `generate.sh` and `generate-dev.sh` (which just run all .sh files in this folder). They're meant to modify the "compiled" HTML files.
+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.
 
 ## 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 the `make-file-lists.sh` script was the first to utilize them, but I've expanded their usage and their current name means "format tags".
+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.
 
-Their purpose is to shorten and abstract certain custom HTML code that I want to use in my pages (but will have to include as-is in the Markdown files). List of scripts that handle ftags:
+On the "backend", they just get replaced with specific HTML. List of scripts that handle ftags:
 
-|Script|ftags|ftag can be anywhere in text|
-|---|---|---|
-|`make-file-lists.awk`|`&&fos`, `&&fs0`, `&&fs`, `&&fod`|No|
-|`make-flags.awk`|`&&gb`|Yes|
-|`make-presentation.awk`|`&&slide`, `&&/slide`, `&&flexer`, `&&centered`, `&&/centered`, `&&fow`, `&&/fow`, `&&fol`, `&&/fol`, `&&font18`, `&&font20`, `&&font27`, `&&font30`, `&&font35`, `&&/font`|No|
+|Script|ftags|
+|---|---|
+|`make-file-lists.awk`|`&&folder`, `&&file`, `&&/files`, `&&ft-TYPE` *(TYPE is one of `photo`, `text`, `zip`, `movie`, `markdown`)*|
+|`make-flags.awk`|`&&gb`|
+|`make-presentation.awk`|`&&presentation`, `&&slide`, `&&/slide`, `&&flexer`, `&&centered`, `&&/centered`, `&&fow`, `&&/fow`, `&&fol`, `&&/fol`, `&&fontSIZE` *(SIZE is one of `18`, `20`, `27`, `30`, `37`)*, `&&/font`|
 
-For more information on how to use the different ftags, consult the specified script.
+Information regarding their usage can be found at the top of their respective script file.
diff --git a/generate-hooks/create-description.awk b/generate-hooks/create-description.awk
index ec0bace..8c0d753 100644
--- a/generate-hooks/create-description.awk
+++ b/generate-hooks/create-description.awk
@@ -1,14 +1,16 @@
-# For every page, the description meta tag is "[DESCRIPTION]", with this we
-# generate it. At most, the first 200 characters from all paragraphs are taken.
+#
+# == About ==
+#
+# Every page has a description and og:description meta tags. These descriptions
+# are generated from the paragraphs, inside the given page.
+# The value for those meta tags is "[DESCRIPTION]" and it gets replaced with
+# either all of the text on the page, or only the first 200 characters.
 
 function appToDesc(l) {
-	# Removes tags and bad characters
-	gsub(/<[^>]*>/, "", l) ; gsub("&#8217;", "'", l) ; gsub(/[^a-zA-Z0-9 '.]/, "", l)
-	# Trims leading and trailing spaces and tabs (if any)
+	gsub(/<[^>]*>/, "", l) ; gsub("&#8217;", "'", l)
+	gsub(/[^a-zA-Z0-9 '.]/, "", l)
 	gsub(/^[ \t]*/, "", l) ; gsub(/[ \t]*$/, "", l)
 
-	# Concatenates the current record to variable and shortens it,
-	# when it gets too long
 	desc = desc l
 	if (length(desc) >= 200) {
 		desc = substr(desc, 1, 197) "..."
diff --git a/generate-hooks/create-file-lists.awk b/generate-hooks/create-file-lists.awk
index 113bca6..7d18bdd 100644
--- a/generate-hooks/create-file-lists.awk
+++ b/generate-hooks/create-file-lists.awk
@@ -1,55 +1,93 @@
-# This is a really rudementary way to make making file lists less HTML-y
-# I made it so:
-# 1) You don't have to write quite as much HTML
-# 2) The Data columns for each file get to be formatted as Markdown (<td> is not recognized as a block-level element, so the stuff inside get formatted https://kristaps.bsd.lv/lowdown/lowdown.5.html#HTML_Blocks)
-
-# Very roughly, each file list has either this:
-# <details><summary>Folder Info</summary> <table> <tr>File Data</tr> </table> </details>
-# or this:
-# <table> <tr>File Data</tr> </table>
-# structure, the difference being that in the first, all of the files are in a folder.
+#
+# == About ==
+#
+# Each file list is a "details" element, that contains a table, each row being a different file
+# or alternatively, just the table on it's own.
+# 
+# -- Result HTML --
+#
+# <details>
+#   <summary>Folder Info</summary>
+#   <table>
+#     <tr>File Data</tr>
+#   </table>
+# </details>
+# or
+# <table>
+#   <tr>File Data</tr>
+# </table>
 
-# In Markdown you type in something like (without the "# " in front):
 #
-# &&fos
-# Description
-# &&file0
-# <td>Data 1</td>
-# <td>Data 1.1</td>
-# <td>Data 1.2</td>
+# == ftags ==
+#
+# &&folder     The text right afterwards is the title of the folder. All files
+#              are hidden inside the collapsed details tag (click to show).
+#              The file table is indented. You cannot have a folder inside a folder.
+#              It can be omitted, and the files table will be shown as-is.
+#
+# &&file       Everything that follows this tag is the data for a file. You should
+#              use &&fd to specify columns of information! Depending on the context,
+#              it might be replaced with the start of a table, closing the summary
+#              and starting table, or closing and opening a table row.
+#
+# &&/files     This tag must exist at the bottom of a file list, no matter if it was
+#              started with or without a &&folder.
+#
+# &&fd         Defines a column of information for a file (row). Practically, it is
+#              replaced with <td>, and </td> is added to the end of the line.
+#              If you don't use it, make sure to have the leading and trailing td tags!
+#
+# &&ft-TYPE    Depending on TYPE, it inserts an image tag that contains the file "icon"
+#              for the corresponding type.
+#              Available values for TYPE: photo, text, zip, movie, markdown
+#
+# -- Placement/Flow --
+#
+# All ftags, except &&fd, can be placed on their own line (empty line above and below)
+# or before/after another ftag.
+# Folder title must be inside the same paragraph as the ftag itself. This means that,
+# after
+# every &&folder ftag, the text can continue directly next to it and/or on new lines,
+# without there being any empty lines (you can add those with <br> or two spaces at
+# line end).
+#
+# -- Example Usage --
+#
+# (I like to indent a bit &&fd ftags, for readability's sake, but you don't have to)
+#
 # &&file
-# <td>Data 2</td>
-# <td>Data 2.1</td>
-# <td>Data 2.2</td>
-# &&fod
+#   &&ft-text
+#   &&fd Notes
+#   &&fd 10 KB
+# &&/files
 #
-# or
+# &&folder Math
+# &&file
+#   &&ft-text
+#   &&fd Homework 1
+# &&file
+#   &&ft-text
+#   &&fd Homework 2
+# &&/files
+#
+# &&folder Art Project<br>
+# Status: 70% complete<br>
+# Note: Reserach Van Gogh paintings
 #
-# &&nos
-# <td>Data 1</td>
-# <td>Data 1.1</td>
-# <td>Data 1.2</td>
 # &&file
-# <td>Data 2</td>
-# <td>Data 2.1</td>
-# <td>Data 2.2</td>
-# &&nod
-
+#   &&fd Painting 1
+#   &&fd 100% Complete
+#
+# &&file
+#   &&fd Painting 2
+#   &&fd 40% Complete
 #
-# And the lines starting with && (I'll call them ftags) get replaced by some HTML. The <td></td> around each file Data is mandatory.
-# &&file0 must only be used on before the very first file data, when files are in a folder. There must be no empty lines, lines mustn't start with spaces, there mustn't be anything around ftags and ftags have to be on their own lines.
-# The commands have fairly intuitive abbreviations:
-# &&nos    no folder start (start file list, without making a folder)
-# &&fos    folder start
-# &&file0    file start of first file in folder (must only be used when items are in a folder!)
-# &&file     file start
-# &&nod    no folder end (end file list, without having made a folder)
-# &&fod    folder end
+# &&/files
 
 BEGIN {
 	fileStarted = 0
 	noFolder    = 1
-	searchEndP  = 0
+	searchEndP  = 0 # Used to remove trailing </p> in file row
 
 	# Special formatting
 	nam[1] = "folder"
diff --git a/generate-hooks/create-flags.awk b/generate-hooks/create-flags.awk
index ad8e1b2..252bdcb 100644
--- a/generate-hooks/create-flags.awk
+++ b/generate-hooks/create-flags.awk
@@ -1,8 +1,17 @@
-# Adds a way to more simply insert flags into text
-# Each flag is represented with an ftag (text that is preceded by &&)
+#
+# == About ==
+#
+# A collection of ftags that generate an image HTML tag, containing the specified
+# flag. This is done, because these tags need to have the unzoomable class, which
+# you can't specify in Markdown.
 
-# Available flags:
-# Great Britain - &&gb
+# == ftags ==
+#
+# &&gb    Great Britain flag
+#
+# -- Placement/Flow --
+#
+# They can reside absolutely anywhere in text.
 
 BEGIN {
 	flag[1] = "gb"
diff --git a/generate-hooks/create-presentation.awk b/generate-hooks/create-presentation.awk
index ae7fedf..7f2cd73 100644
--- a/generate-hooks/create-presentation.awk
+++ b/generate-hooks/create-presentation.awk
@@ -1,30 +1,73 @@
-# A presentation is just a markdown file, with some added ftags for formatting into a presentation layout.
-# This means all presentations will change how they look with changes to the main styles.css. It also means
-# that they follow the light/dark mode setting.
-# Each slide is the size of a horizontal A4 piece of paper. This makes it easy to print (and there is a dedicated
-# print button).
-# The whole system is based on flexboxes. The only real way to control how items are aligned is via a row and column
-# directed flexboxes. This isn't the most efficient, but it's fine. And if there are performance issues, the
-# presentation can always be "printed" to a PDF and consumed that way.
+#
+# == About ==
+#
+# This is my way of making slide-based presentations. In short, it just groups
+# Markdown formatting into rectangles and adds options for layout formatting.
+# Each slide is the size of a landscape-oriented A4 sheet of paper. Light/dark
+# mode settings are respected (of course).
+# Currently, this appliest only to pages under the "talks" folder.
 
-# Currently you can have normal paragraphs and heading around a presentation, and those won't be printed out.
-# But you can have only ONE presentation per page!!!
-# All ftags that have a closing tag, and &&presentation, need one line above and below them (but you don't
-# need the first and last line of file to be empty).
-
-# &&presentation    Required. Adds the control panel and JavaScript script. Must be the very first one!
-# &&slide           Starts a slide. Slides are the main pages that hold content and are used for navigation.
+#
+# == ftags ==
+#
+# &&presentation    Must appear before any other presentation ftags.
+#                   It "loads" everything necessary for a presentation, that being
+#                   the navigation bar and logic script (which also inserts the
+#                   custom stylesheet).
+#                   Can be only one per page. Also refer to -- Surroundings --
+# 
+# &&slide           Everything below this tag is part of a slide. Each slide is
+#                   presented in the order it appears in.
 # &&/slide          Ends (the last started) slide.
-# &&flexer          An empty container with flex: 1. Use it for spacing out stuff.
-# &&centered        Aligns text to the center.
-# &&/centered       Ends (the last started) centered text.
-# &&fow             Flexbox, with flex-direction row.
-# &&/fow            Ends (the last started) fow.
-# &&fol             Flexbox, with flex-direction column.
-# &&/fol            Ends (the last started) fol.
+#
+# &&fow             A row of paragraphs, where each item is evenly sized and is
+#                   spaced out horizontally. In the HTML, it is a simple flexbox.
+#                   This is one of the two main ways to configure how content is
+#                   laid out on a slide.
+# &&/fow            Every HTML element/paragraph between &&fow and &&/fow is an
+#                   item that will be laid out.
+#
+# &&fol             A column of paragraphs, where each item is evenly sized and is
+#                   spaced out vertically. In the HTML, it is a simple flexbox.
+#                   This is one of the two main ways to configure how content is
+#                   laid out on a slide.
+# &&/fol            Every HTML element/paragraph between &&fol and &&/fol is an
+#                   item that will be laid out.
+# 
+# &&flexer          An empty container, which can be used as a blank space item
+#                   inside &&fow or &&fol. In the styling, it just has `flex: 1`.
+#
+# &&centered        Aligns text to the center, literally.
+# &&/centered       Text between &&centered and &&/centered is aligned.
+#
+# &&fright          Aligns element and the text inside to the right. In the styling,
+#                   it just has text-align and float set to right.
+# &&/fright         Text between &&fright and &&/fright is aligned to the right
+#
+# &&fontSIZE        Changes to font size to SIZE, in pixels. Default size is 24px.
+#                   Available values for SIZE: 18, 20, 27, 30, 37
+# &&/font           Text between &&fontSIZE and &&/font is sized accordingly
+#
+# -- Surroundings --
+#
+# As stated, there can only be one presentation per page.
+# Everything that is around a presentation and it's slides is normally hidden
+# during presenting mode, but will show up if you try to print the presentation.
+# Exceptions to this rule are headings and paragraphs, which won't show up in
+# presenting mode or during print.
+#
+# -- Placement/Flow --
+#
+# All ftags can be placed on their own line, or in a line with other ftags.
+# The only requirement is that such a line must start with an ftag, ftags in the
+# middle of text aren't recognized.
+#
+# -- Example Usage --
+#
+# Refer to src/talks/demo.md
 
 BEGIN {
-	if (substr(FILENAME, "talks") == 0) exit
+	if (substr(ARGV[1], "talks") == 0) exit # FILENAME isn't available yet
 
 	# Exceptions to the normal format
 	names[ 1] = "presentation"
diff --git a/generate-hooks/create-title.awk b/generate-hooks/create-title.awk
index f1eaa4f..24d5f7d 100644
--- a/generate-hooks/create-title.awk
+++ b/generate-hooks/create-title.awk
@@ -1,3 +1,11 @@
+#
+# == About ==
+#
+# Every page has a og:title meta tag, which has to be generated from the page
+# itself. The title tag is automatically filled in by ssg.
+# The value for the meta tag is "[TITLE]" and it gets replaced with all text
+# inside first h1 header tag.
+
 BEGIN {
 	h1Index = 0