[Presentation] Updated documentation and slightly reworked formatting

1 files changed, 91 insertions, 77 deletions

diff --git a/awk-edits/Presentation.awk b/awk-edits/Presentation.awk
index 40468fb..31a834f 100644
--- a/awk-edits/Presentation.awk
+++ b/awk-edits/Presentation.awk
@@ -3,9 +3,10 @@
 #
 # This is my way of making slide-based presentations. In short, it just groups
 # Markdown formatting into rectangles and adds options for layout formatting.
+# Inside each slide, normal element flow is respected.
 # 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, this is active only in pages under the "talks" folder.
 
 #
 # == ftags ==
@@ -16,53 +17,44 @@
 #                   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
+# &&slide           Everything following this tag is part of a slide. Each slide is
 #                   presented in the order it appears in.
 # &&/slide          Ends (the last started) slide.
 #
-# &&frow            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.
-# &&/frow           Every HTML element/paragraph between &&frow and &&/frow is an
-#                   item that will be laid out.
+# &&clide           Same as &&slide, but everything following is centered
+#                   vertically. Uses flexbox.
+# &&/slide          Ends (the last started) clide. Not compatible with &&/slide!
 #
-# &&fcol            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.
-# &&/fcol           Every HTML element/paragraph between &&fcol and &&/fcol is an
-#                   item that will be laid out.
+# &&table           Starts a table, where everything following it is formatted as a
+#                   table cell in a row.
+# &&ftable          Same as &&table, but all colums have the same width.
+# &&tarow           Ends the last started row and begins a new row.
+#                   Effectively everything following it is on a new row.
+# &&/table          Ends (the last started) (table row and) table or ftable.
+#
+# &&linebN          Adds a line break (vertical spacing) of N (text) lines.
+#                   Spacing is equivalent to N em.
+#                   Available values for N: 1, 2, 3, 4, 5, 6, 7, 8, 9
 # 
-# &&flexer          An empty container, which can be used as a blank space item
-#                   inside &&frow or &&fcol. In the styling, it just has `flex: 1`.
+# &&fontSIZE        Changes font size to SIZE, in pixels. Default size is 30px.
+#                   Available values for SIZE: 18, 20, 22, 25, 27, 35
+# &&/font           Text between &&fontSIZE and &&/font is sized accordingly
 #
-# &&centered        Aligns text to the center, literally.
+# &&centered        Center horizontally (only) text.
 # &&/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          Aligns following elements and text to the 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
-#
-# &&frcen           Shorthand for "&&frow &&flexer &&centered"
-#                   Useful for horizontally centered items
-# &&/frcen          Shorthand for "&&/centered &&flexer &&/frow"
-#
-# &&clide           Shorthand for "&&slide &&flexer &&centered"
-#                   Useful for section pages
-# &&/clide          Shorthand for "&&/centered &&flexer &&/slide"
+# &&cont            Basic container with no properties. Useful if you need to group
+#                   multiple elements into one table cell.
+# &&/cont           Ends (the last started) &&cont
 #
 # -- 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.
+# during presenting mode and while printing.
 #
 # -- Placement/Flow --
 #
@@ -70,69 +62,94 @@
 # The only requirement is that such a line must start with an ftag, ftags in the
 # middle of text aren't recognized.
 #
+# -- Regarding flex --
+#
+# The older versions of the script, prior to commit
+# 687ff3652e5695183ba1691e7d4b94470f8407b3
+# used extensively flexbox for element alignment. This was done with the hope that
+# spacing out elements evenly and centering them would be very easy, which turned
+# out to be false.
+#
+# Now, the only thing that uses flexbox is &&clide, and it only allows to center
+# everything in the slide vertically.
+# Vertical centerings for portions of elements can be done with &&linebN, which,
+# though imperfect, does the job very well and should suffice.
+# Evenly spacing out elements next to each other can be done with &&table and
+# &&ftable.
+#
 # -- Example Usage --
 #
-# Refer to src/talks/demo.md
+# Refer to src/talks/demo/index.md
 
 BEGIN {
 	nopresentation=substr(ARGV[1], "talks") == 0 # FILENAME isn't available yet
 
-	# Exceptions to the normal format
+	# names is name of ftag, meaning if `names[i] = "examp"` the ftag will be &&examp
+	# ended specifies how the HTML tag is ended
+	#     `ended[i] = 0` means no closing ftag (so no &&/examp)
+	#     `ended[i] = 1` means &&/examp exists
+	#     `ended[i] = 2` means self-closing, so no &&/examp, but &&examp includes the closing tag
+	#
+	# &&examp is usually replaced by `<div class="examp">`
+	# &&/examp is usually replaced by `</div>`
+	# in case ended[i] = 2, &&examp is replaced by `<div class="examp"></div>`
+
+	# Main elements and exceptions to the normal replace format
 	names[ 1] = "presentation"
 	ended[ 1] = 0
-	names[ 2] = "&#47;font" # all font ftags can be closed with a &&/font
-	ended[ 2] = 0
-	names[ 3] = "table"
+	names[ 2] = "slide"
+	ended[ 2] = 1
+	names[ 3] = "clide"
 	ended[ 3] = 1
-	names[ 4] = "ftable"
+	names[ 4] = "table"
 	ended[ 4] = 1
-	names[ 5] = "tarow"
+	names[ 5] = "ftable"
 	ended[ 5] = 0
+	names[ 6] = "tarow"
+	ended[ 6] = 0
+	names[ 7] = "&#47;font" # all font ftags can be closed with a &&/font
+	ended[ 7] = 0
 
 	# Line breaks
-	names[ 6] = "lineb1"
-	ended[ 6] = 2
-	names[ 7] = "lineb2"
-	ended[ 7] = 2
-	names[ 8] = "lineb3"
+	names[ 8] = "lineb1"
 	ended[ 8] = 2
-	names[ 9] = "lineb4"
+	names[ 9] = "lineb2"
 	ended[ 9] = 2
-	names[10] = "lineb5"
+	names[10] = "lineb3"
 	ended[10] = 2
-	names[11] = "lineb6"
+	names[11] = "lineb4"
 	ended[11] = 2
-	names[12] = "lineb7"
+	names[12] = "lineb5"
 	ended[12] = 2
-	names[13] = "lineb8"
+	names[13] = "lineb6"
 	ended[13] = 2
-	names[14] = "lineb9"
+	names[14] = "lineb7"
 	ended[14] = 2
+	names[15] = "lineb8"
+	ended[15] = 2
+	names[16] = "lineb9"
+	ended[16] = 2
 
 	# Font sizes
-	names[15] = "font18"
-	ended[15] = 0
-	names[16] = "font20"
-	ended[16] = 0
-	names[17] = "font22"
+	names[17] = "font18"
 	ended[17] = 0
-	names[18] = "font25"
+	names[18] = "font20"
 	ended[18] = 0
-	names[19] = "font27"
+	names[19] = "font22"
 	ended[19] = 0
-	names[20] = "font35"
+	names[20] = "font25"
 	ended[20] = 0
+	names[21] = "font27"
+	ended[21] = 0
+	names[22] = "font35"
+	ended[22] = 0
 
 	# Everything else
-	names[21] = "slide"
-	ended[21] = 1
-	names[22] = "clide"
-	ended[22] = 1
 	names[23] = "centered"
 	ended[23] = 1
-	names[24] = "cont"
+	names[24] = "fright"
 	ended[24] = 1
-	names[25] = "fright"
+	names[25] = "cont"
 	ended[25] = 1
 
 	pres = ORS \
@@ -144,12 +161,7 @@ BEGIN {
 "		</nav>" ORS \
 "		<script type=\"text/javascript\" src=\"/scripts/presentation.js\" integrity=\"sha512-5u+Yy4xqrGKYXeUrzgaXXj7dqNtFUnlaPtfz86v9nT+l8osWfLnjLOU/vRv2Hmx7wsmCdb3pfurH0/hQHLQOSA==\" crossorigin=\"anonymous\"></script>"
 
-	pat[1] = "&#38;&#38;presentation"
-	rep[1] = pres
-	pat[2] = "&#38;&#38;&#47;font"
-	rep[2] = "</div>"
-
-	for (i = 3; i <= length(names); i++) {
+	for (i = 1; i <= length(names); i++) {
 		pat[i] = "&#38;&#38;" names[i]
 		rep[i] = "<div class=\"" names[i] "\">"
 
@@ -162,12 +174,14 @@ BEGIN {
 		}
 	}
 
-	rep[3] = "<div class=\"layout-table\"><div class=\"layout-row\">"
-	crep[3] = "</div></div>"
-	rep[4] = "<div class=\"layout-table fixed-layout\"><div class=\"layout-row\">"
-	rep[5] = "</div><div class=\"layout-row\">"
-	rep[22] = "<div class=\"slide clide\"><div></div><div>"
-	crep[22] = "</div><div></div></div>"
+	rep[ 1] = pres
+	rep[ 3] = "<div class=\"slide clide\"><div></div><div>" # flex-col + flex:1 + <div>
+	crep[3] = "</div><div></div></div>"                     # </div>   + flex:1 + /flex-col
+	rep[ 4] = "<div class=\"layout-table\"><div class=\"layout-row\">" # <table><tr>  (layout-row > * is td)
+	crep[4] = "</div></div>"                                           # </tr><table>
+	rep[ 5] = "<div class=\"layout-table fixed-layout\"><div class=\"layout-row\">" # <table><tr>  (layout-row > * is td)
+	rep[ 6] = "</div><div class=\"layout-row\">" # </tr><tr>
+	rep[ 7] = "</div>" # &&/font
 }
 
 function presentationSubstitute(ind) {