hswg: add a minimal README.adoc

Moving the example script from somewhere else.

1 files changed, 62 insertions, 0 deletions

diff --git a/hswg/README.adoc b/hswg/README.adoc
new file mode 100644
index 0000000..3cefe5b
--- /dev/null
+++ b/hswg/README.adoc
@@ -0,0 +1,62 @@
+hswg: a static website generator
+================================
+
+hswg wraps libasciidoc to make it understand more syntax, namely
+two-line/underlined titles, and can be run either as a filter, or as a simple
+wiki-like site generator.
+
+Gitea/cgit AsciiDoc processor
+-----------------------------
+Wrap hswg in the following script to give it a few superpowers:
+
+```
+#!/bin/sh
+# Make this also work for cgit which, strangely enough, is willing to render
+# /anything/ via the /about route, only passing through image/* unchanged.
+if [ -z "$GITEA_PREFIX_SRC" ]; then
+    test "${1%.adoc}" != "$1" || exit 1
+    cgit_fixups='s/<div class="content">/<div>/'
+    export GITEA_PREFIX_SRC=. GITEA_PREFIX_RAW=.
+fi
+
+# libasciidoc can't be helped in other ways so far, adding support for:
+#  - the original 'italics' syntax
+#  - double-line headings (part of haven's hswg which invokes libasciidoc)
+#  - make links to other documents work, normally an attribute could be used
+perl -pe "s|'([-~/\\.\\w]+)'|_\$1_|g;" | hswg 2>/dev/null | \
+    perl -pe 's|(href=")([^/][^:]*?")|$1$ENV{GITEA_PREFIX_SRC}/$2|;' \
+        -e 's|(src=")([^/][^:]*?")|$1$ENV{GITEA_PREFIX_RAW}/$2|;' \
+        -e "$cgit_fixups"
+```
+
+Then, to set it up in Gitea, include the following snippet in your _app.ini_:
+
+```
+[markup.asciidoc]
+ENABLED         = true
+FILE_EXTENSIONS = .adoc,.asciidoc
+RENDER_COMMAND  = /usr/local/bin/hswg-gitea
+IS_INPUT_FILE   = false
+```
+
+Similarly for cgit, the following _cgitrc_ snippet might do the job:
+
+```
+about-filter=/usr/local/bin/hswg-gitea
+readme=:README.adoc
+```
+
+If parsing fails for some reason, the contents will be wrapped in HTML verbatim
+as plain text.
+
+Wiki mode
+---------
+The program will read a Go template for the index page from its standard input,
+and another template for rendered pages from the path given as its first
+argument.  The second argument specifies the output filename for the index page,
+and the last one is the document directory.
+
+Consult the source code for a list template variables.
+
+All pages will be initially rerendered on startup, and then the directory will
+be watched for changes in real time using the inotify API.