From af146f65e4e4e3237dc47752fde42e5d5d1ef25d Mon Sep 17 00:00:00 2001
From: Jaidyn Ann <10477760+JadedCtrl@users.noreply.github.com>
Date: Thu, 28 Mar 2024 02:13:28 -0500
Subject: [PATCH] Basic documentation of each function

---
 fedi2html.sh | 38 ++++++++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/fedi2html.sh b/fedi2html.sh
index 85780b1..14eb917 100755
--- a/fedi2html.sh
+++ b/fedi2html.sh
@@ -6,7 +6,8 @@
 # Date:
 #―――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――
 
-
+# Return the ID of a post, based on its URL.
+#     url_id $url
 url_id() {
 	local url="$1"
 	# Pleroma-style URLs:  https://jam.xwx.moe/notice/Ac6PIZAP0ZzkMTYBBg
@@ -21,6 +22,8 @@ url_id() {
 }
 
 
+# Return the server (including protocol) of a post, based on its URL.
+#     url_server $url
 url_server() {
 	local url="$1"
 	local protocol="$(echo "$url" | grep --only-matching '[[:alnum:]]*://')"
@@ -31,6 +34,8 @@ url_server() {
 }
 
 
+# Make a request to the /api/v1/statuses/:id/$request API endpoint.
+#     statuses_api_request $post_url $request
 statuses_api_request() {
 	local post_url="$1"
 	local api_request="$2"
@@ -45,12 +50,16 @@ statuses_api_request() {
 }
 
 
+# Require the context-JSON of a post, by URL.
+#     fetch_post_context $url
 fetch_post_context() {
 	local url="$1"
 	statuses_api_request "$url" "context"
 }
 
 
+# Given a post URL, request its JSON.
+#     fetch_post $url
 fetch_post() {
 	local url="$1"
 	statuses_api_request "$url"
@@ -110,6 +119,11 @@ ATTACH_IMAGE_TEMPLATE='
 
 EMOJI_TEMPLATE='<img class="emoji" src="$EMOJI_URL" alt="$EMOJI_SHORTCODE" title="$EMOJI_SHORTCODE">'
 
+
+# Accepts a string over stdin; it will replace all emoji shortcodes along stdin
+# input with appropriate <img> HTML, based on $EMOJI_TEMPLATE, and based on
+# a post’s JSON.
+#     echo ":blobcat:" | replace_emojis $post_data
 replace_emojis() {
 	local post_data="$1"
 	local emojis="$(echo "$post_data" | jq -r '.emojis[]|(.url + "\t" + .shortcode)')"
@@ -129,13 +143,14 @@ replace_emojis() {
 }
 
 
+# Given a post’s JSON data, return the appropriate HTML corresponding to its
+# media attachments, if any. Will return an empty string if none.
+#     media_attachments $post_data
 media_attachments() {
 	local post_data="$1"
 	local attachments="$(echo "$post_data" | jq -r '.media_attachments[]|(.type + "\t" + .url + "\t" + .description + "\t" + .preview_url)')"
 	local IFS="
 "
-
-	echo "$attachments" > /tmp/d
 	for line in $attachments; do
 		local ATTACH_TYPE="$(echo "$line" | awk -F'\t' '{print $1}')"
 		local ATTACH_URL="$(echo "$line" | awk -F'\t' '{print $2}')"
@@ -150,17 +165,33 @@ media_attachments() {
 	done
 }
 
+
+# Sanitize a template-string.
+# AKA, escape quotation-marks.
+#     prep_template $template
 prep_template() {
 	local template="$1"
 	echo "$template" \
 		| sed 's%\"%\\\"%g'
 }
 
+
+# Rough replacement for gettext’s envsubst. Safe!
+# This will evaluate a string’s shell variables (somewhat) safely
+# Probably not good for general use — but for our purposes, it only subsitutes
+# along the “first level.” So environment variables are replaced, but those
+# variables’ contents (AKA, post contents) aren’t evaluated.
+#     env_subst $template
+#     env_subst "$SHELL"  →  "/bin/sh"
 env_subst() {
 	local template="$1"
 	eval "echo \"$(prep_template "$template")\""
 }
 
+
+# Given a note’s JSON, render it as HTML.
+# The most important part of the script!
+#     render_post $post_data
 render_post() {
 	local post_data="$1"
 	local ACCOUNT_URL="$(echo "$post_data"    | jq -r .account.url)"
@@ -173,4 +204,3 @@ render_post() {
 	local POST_ATTACHMENTS="$(media_attachments "$post_data")"
 	env_subst "$POST_TEMPLATE"
 }
-