From 5b432fcc0bdee654b225ca2b47cc505e8fb1cf12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C5=99emysl=20Eric=20Janouch?= <p@janouch.name>
Date: Sun, 27 Jun 2021 00:00:19 +0200
Subject: [PATCH] hswg: add a minimal README.adoc

Moving the example script from somewhere else.
---
 README.adoc      |  4 +---
 hswg/README.adoc | 62 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 63 insertions(+), 3 deletions(-)
 create mode 100644 hswg/README.adoc

diff --git a/README.adoc b/README.adoc
index 982c287..9f43933 100644
--- a/README.adoc
+++ b/README.adoc
@@ -96,9 +96,7 @@ Only UTF8_STRING-convertible selections are synchronized.
 
 hswg -- static website generator
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Wraps libasciidoc to make it understand more syntax, namely two-line/underlined
-titles, and can be run either as an AsciiDoc processor for my Gitea, or as
-a trivial wiki-like site generator.
+link:hswg/README.adoc[See hswg's README for details.]
 
 ht -- terminal emulator
 ~~~~~~~~~~~~~~~~~~~~~~~
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.