1 files changed, 213 insertions, 0 deletions

@@ -0,0 +1,213 @@
+#!/bin/awk -f
+# DOC AWK
+# ======
+#
+# A quick-and-dirty literate-programming-style documentation generator
+# inspired by [docco][].
+#
+# by Case Duckworth <acdw@acdw.net>
+#
+# Source available under the [Good Choices License][gcl].
+#
+# [gcl]: https://acdw.casa/gcl Good Choices License
+#
+# There's a lot of quick-and-dirty "literate programming tools" out there, many
+# of which were inspired by, and also borrowed from, docco.  I was particularly
+# interested in [shocco][], written in POSIX shell (of which I am a fan).
+#
+# Notably missing, however, was a converter of some kind written in AWK.  Thus,
+# DOC AWK was born.
+#
+# This page is the result of DOC AWK working on itself.  Not bad for < 250 lines
+# including commentary!  You can pick up the raw source code of doc.awk [in its
+# git repository][git] to use it yourself.
+#
+# [docco]: https://ashkenas.com/docco/
+# [shocco]: https://rtomayko.github.io/shocco/
+# [git]: https://git.acdw.net/docawk
+#
+# Code
+# ----
+BEGIN {
+        # All the best awk scripts start with a `BEGIN` block.  In this one, we
+        # set a few variables from the environment, with defaults.  I use the
+        # convenience function `getenv`, further down this script, to make it
+        # easier.
+        #
+        # First, the comment regex.  This regex detects a comment *line*, not an
+        # inline comment.  By default, it's set up for awk, shell, and other
+        # languages that use `#` as a comment delimiter, but you can make it
+        # whatever you want.
+        COMMENT = getenv("DOCAWK_COMMENT", COMMENT, "^[ \t]*#+[ \t]*")
+        # You can set `DOCAWK_TEXTPROC` to any text processor you want, but the
+        # default is the vendored `mdown.awk` script in this repo.  It's from
+        # [d.awk](https://github.com/wernsey/d.awk).
+        TEXTPROC = getenv("DOCAWK_TEXTPROC", TEXTPROC, "./mdown.awk")
+        # You can also set the processor for code sections of the source file;
+        # the included `htmlsafe.awk` simply escapes <, &, and >.
+        CODEPROC = getenv("DOCAWK_CODEPROC", CODEPROC, "./htmlsafe.awk")
+        # Usually, a file header and footer are enough for most documents.  The
+        # defaults here are the included header.html and footer.html, since the
+        # default output type is html.
+        #
+        # Each of these documents are actually *templates*, with keys that can
+        # expand to variables inside of `@@VARIABLE@@`.  This is mostly
+        # for title expansion.
+        HEADER = getenv("DOCAWK_HEADER", HEADER, "./header.html")
+        FOOTER = getenv("DOCAWK_FOOTER", FOOTER, "./footer.html")
+}
+
+# Because `FILENAME` is unset during `BEGIN`, template expansion that attempts
+# to view the filename doesn't work.  Thus, I need a state variable to track
+# whether we've started or not (so that I don't print a header with every new
+# file).
+! begun {
+        # The template array is initialized with the document's title.
+        TV["TITLE"] = get_title()
+        # Print the header here, since if multiple files are passed to DOC AWK
+        # they'll all be concatenated anyway.
+        file_print(HEADER)
+}
+
+# `doc.awk` is multi-file aware.  It also removes the shebang line from the
+# script if it exists, because you probably don't want that in the output.
+#
+# It wouldn't be a *bad* idea to make a heuristic for determining the type of
+# source file we're converting here.
+FNR == 1 {
+        begun = 1
+        if ($0 ~ COMMENT) {
+                lt = "text"
+        } else {
+                lt = "code"
+        }
+        if ($0 !~ /^#!/) {
+                bufadd(lt)
+        }
+        next
+}
+
+# The main logic is quite simple: if a given line is a comment as defined by
+# `DOCAWK_COMMENT`, it's in a text block and should be treated as such;
+# otherwise, it's in a code block.  Accumulate each part in a dedicated buffer,
+# and on a switch-over between code and text, print the buffer and reset.
+$0 !~ COMMENT {
+        lt = "code"
+        bufprint("text")
+}
+
+$0 ~ COMMENT {
+        lt = "text"
+        bufprint("code")
+        sub(COMMENT, "", $0)
+}
+
+{
+        bufadd(lt)
+}
+
+# Of course, at the end there might be something in either buffer, so print that
+# out too.  I've decided to put text last for the possibility of ending commentary.
+END {
+        bufprint("code")
+        bufprint("text")
+        file_print(FOOTER)
+}
+
+
+# Functions
+# ---------
+#
+# *bufadd*: Add a STR to buffer TYPE.  STR defaults to $0, the input record.
+function bufadd(type, str)
+{
+        buf[type] = buf[type] (str ? str : $0) "\n"
+}
+
+# *bufprint*: Print a buffer of TYPE.  Automatically wrap the code blocks in a
+# little HTML code block.  I could maybe have a DOCAWK_CODE_PRE/POST and maybe
+# even one for text too, to make it more extensible (to other markup languages,
+# for example).
+function bufprint(type)
+{
+        buf[type] = trim(buf[type])
+        if (buf[type]) {
+                if (type == "code") {
+                        printf "<pre><code>"
+                        printf(buf[type]) | CODEPROC
+                        close(CODEPROC)
+                        print "</code></pre>"
+                } else if (type == "text") {
+                        print(buf[type]) | TEXTPROC
+                        close(TEXTPROC)
+                }
+                buf[type] = ""
+        }
+}
+
+# *file_print*: Print FILE line-by-line.  The `> 0` check here ensures that it
+# bails on error (-1).
+function file_print(file)
+{
+        if (file) {
+                while ((getline l < file) > 0) {
+                        print template_expand(l)
+                }
+                close(file)
+        }
+}
+
+# *get_title*: get the title of the current script, for the expanded document.
+# If variables are set, use those; otherwise try to figure out the title from
+# the document's basename.
+function get_title()
+{
+        title = getenv("DOCAWK_TITLE", TITLE)
+        if (! title) {
+                title = FILENAME
+                sub(/.*\//, "", title)
+        }
+        return title
+}
+
+# *getenv*: a convenience function for pulling values out of the environment.
+# If an environment variable ENV isn't found, test if VAR is set (i.e., `doc.awk
+# -v var=foo`.) and return it if it's set.  Otherwise, return the default value
+# DEF.
+function getenv(env, var, def)
+{
+        if (ENVIRON[env]) {
+                return ENVIRON[env]
+        } else if (var) {
+                return var
+        } else {
+                return def
+        }
+}
+
+# *template_expand*: expand templates of the form `@@template@@` in the text.
+# Currently it only does variables, and works by line.
+#
+# Due to the way awk works, template variables need to live in their own special
+# array, `TV`.  I'd love it if awk had some kind of `eval` functionality, but at
+# least POSIX awk doesn't.
+function template_expand(text)
+{
+        if (match(text, /@@[^@]*@@/)) {
+                var = substr(text, RSTART + 2, RLENGTH - 4)
+                new = substr(text, 1, RSTART - 1)
+                new = new TV[var]
+                new = new substr(text, RSTART + RLENGTH)
+        } else {
+                new = text
+        }
+        return new
+}
+
+# *trim*: remove whitespace from either end of a string.
+function trim(str)
+{
+        sub(/^[ \n]*/, "", str)
+        sub(/[ \n]*$/, "", str)
+        return str
+}