better documentation

4 files changed, 99 insertions, 32 deletions

diff --git a/README.md b/README.md
index 307ff614..2ed58999 100644
--- a/README.md
+++ b/README.md
@@ -1,46 +1,103 @@
-buetow.org Gemini capsule
-=========================
+The buetow.org internet site
+============================
 
-This is the source code of my Gemini capsule. You can reach the site(s) here:
+This is the source code of my personal internet site. All content is written in Gemini Gemtext format, but the script `buetow.org.sh` generates multiple other static output formats from it. You can reach the site(s)...
 
-* Via Gemini/Gemtext : [gemini://buetow.org](gemini://buetow.org)
-* Via HTTP/HTML: [https://buetow.org](https://buetow.org)
-* [Gemini Webproxy](https://portal.mozz.us/gemini/buetow.org)
-* [GitHub Markdown](https://github.com/snonux/buetow.org/blob/master/content/md/index.md)
-* [GitHub Page](https://snonux.github.io/buetow.org)
+* Via Gemini/Gemtext: [gemini://buetow.org](gemini://buetow.org) (You need a Gemini client for this)
+* Via "normal" HTML: [https://buetow.org](https://buetow.org) (Actually it's XHTML Transitional 1.0)
+* Via [Gemini Webproxy](https://portal.mozz.us/gemini/buetow.org)
+* Via [GitHub Markdown](https://github.com/snonux/buetow.org/blob/master/content/md/index.md)
+* Via [GitHub Page](https://snonux.github.io/buetow.org) (from Markdown)
 
-## Software I use to maintain this capsule
+## Software I use to maintain this site
 
 * Text editor: [Vim](https://www.vim.org)
 * Gemini server: [a-h/gemini](https://github.com/a-h/gemini)
 * Some Bash scripting (GNU Bash probably 5.x or higher required)
-* ShellCheck is also required to be installed.
+* ShellCheck is also required, otherwise `buetow.org.sh` refuses to do anything :-)
+* Web server: [Apache HTTPD](https://httpd.apache.org) (for "normal" HTML site)
 
-## HTTP fallback software used
+# Getting started
 
-* Web server: [Apache HTTPD](https://httpd.apache.org)
+## Requirements
 
-# Usage
+These are the requirements of the `buetow.org.sh` static site generator script:
 
-To get started just clone this repo (master branch) and run `./buetow.org.sh`. You
-will will be prompted with further instructions.
+* GNU Bash 5.x or higher
+* ShellCheck installed
+* GNU Sed
+* GNU Date
+* Git
 
-Once done, you can edit the Gemtext source and then use the buetow.org.sh script
-to generate the other output formats such as:
+The script was tested on a recent Fedora Linux. For macOS you would need to install GNU Sed, GNU Date, and a newer version of Bash (e.g via Homebrew).
 
-* HTML
-* Markdown (works also with GitHub pages as you saw)
-* Meta (that's only generating meta info for the blog post, used for Atom feed generation)
+## Usage
 
-Do a `./buetow.org.sh --help` for a list of all available arguments.
+So you want such a pretty internet site too?
 
-## TODO
+To get started, just clone this repo (master branch) and run `./buetow.org.sh`. You will will be prompted with further instructions.
+
+You will notice soon, that all site content is located in `../buetow.org-content/` (you can configure the `BASE_CONTENT_DIR` in `buetow.org.conf`). There is one sub-directory per output format, e.g.:
+
+```
+../buetow.org-content/gemtext
+../buetow.org-content/html
+../buetow.org-content/md
+../buetow.org-content/meta
+```
+
+### Alternative config file path
+
+If you don't want to mess with `buetow.org.conf`,  you can use an alternative config file path by setting the `CONFIG_FILE_PATH` environment variable, e.g.:
+
+```
+export CONFIG_FILE_PATH=~/.config/my-site.geek.conf
+./buetow.org.sh --generate
+```
+
+### What is what
+
+Whereas, you only want to directly edit/add/remove content in the `gemtext` folder. The `buetow.org.sh` then will take the Gemtext and update all other formats accordingly. Summary of what is what:
+
+* `gemtext`: The Gemini Gemtext markup files of the internet site.
+* `html`: The XHTML version of it.
+* `md`: The Markdown version of it. 
+* `meta`: Some meta data of all Gemtext blog posts. It's used by `buetow.org.sh` internally for Atom feed generation.
+
+### Special HTML configuration
+
+You will find the `./header.html.part` and `./footer.html.part` files, they are minimal template files for the HTML generation.
+
+### Special Markdown configuraiton
+
+`buetow.org.sh` will never touch the `../buetow.org-content/md/_config.yml` file (if it exists). That's a special configuration file for GitHub Pages.
+
+## Store all formats in Git
+
+I personally have for each directory in `../buetow.org-content/` a separate Git repository configured. So whenever something has changed it will be updated/added/removed to version control. The following will run the generator and commit everything to Git:
+
+```
+USE_GIT=yes ./buetow.org --generate
+```
+
+And the following will additionally perform a `git pull` and `git push` afterwards;
+
+```
+USE_GIT=yes GIT_PUSH=yes ./buetow.org --generate
+```
+
+## Finito
+
+After running `./buetow.org --genreate` you will have all static files ready to be published. But before you do that you could preview the content with `firefox ../buetow.org-content/html/index.html` or `glow ../buetow.org-content/md/index.md` (you get the idea).
+
+Have also a look at the generated `atom.xml` files. They make sense (at least) for Gemtext and HTML.
+
+Now it is up to you to setup a Gemini server for the Gemtext, a Webserver for the HTML and/or a GitHub page for the Markdowns.
+
+# TODO
 
 These are things I want to do with this project in near future:
 
-* Speed it up a bit: Make it so, that only changed .gmi files (or changed HTML templates) result into re-generating other formats.
 * Write a blog post about buetow.org.sh script
 * Custom alt.buetow.org domain for GitHub page.
-* Read through this README and make sure usage and purpose is clear.
-* Add custom config file support (check alt location), and add instructions to the setup wizzard.
-* Test + fix on macOS
+* Test + fix on macOS (I havn't tested it for macOS fully yet)
diff --git a/buetow.org.conf b/buetow.org.conf
index c0aac6f3..effeaef6 100644
--- a/buetow.org.conf
+++ b/buetow.org.conf
@@ -5,3 +5,5 @@ declare -xr EMAIL='comments@mx.buetow.org'
 declare -xr IMAGE_PATTERN='\.(jpg|png|gif)$'
 declare -xr ATOM_MAX_ENTRIES=42
 declare -xr CONTENT_BASE_DIR=../buetow.org-content
+declare -xr HTML_HEADER=./header.html.part
+declare -xr HTML_FOOTER=./header.html.part
diff --git a/buetow.org.sh b/buetow.org.sh
index 1564fb9e..60113e10 100755
--- a/buetow.org.sh
+++ b/buetow.org.sh
@@ -14,7 +14,14 @@ readonly DATE
 readonly SED
 readonly GREP
 
-source buetow.org.conf
+set -e
+
+if [[ -n "$CONFIG_FILE_PATH" ]]; then
+    source "$CONFIG_FILE_PATH"
+else
+    source ./buetow.org.conf
+fi
+
 source ./packages/assert.source.sh
 source ./packages/git.source.sh
 source ./packages/atomfeed.source.sh
@@ -24,8 +31,6 @@ source ./packages/html.source.sh
 source ./packages/log.source.sh
 source ./packages/md.source.sh
 
-set -e
-
 help () {
     cat <<HELPHERE
 $0's possible arguments:
diff --git a/packages/generate.source.sh b/packages/generate.source.sh
index 910d2502..0e1f2e25 100644
--- a/packages/generate.source.sh
+++ b/packages/generate.source.sh
@@ -76,10 +76,12 @@ generate::_fromgmi () {
     local dest_dir=$(dirname "$dest")
 
     test ! -d "$dest_dir" && mkdir -p "$dest_dir"
+
     if [[ "$format" == html ]]; then
-        cat header.html.part > "$dest.tmp"
+        cat "$HTML_HEADER" > "$dest.tmp"
         html::fromgmi < "$src" >> "$dest.tmp"
-        cat footer.html.part >> "$dest.tmp"
+        cat "$HTML_FOOTER" >> "$dest.tmp"
+
     elif [[ "$format" == md ]]; then
         md::fromgmi < "$src" >> "$dest.tmp"
     fi
@@ -88,6 +90,7 @@ generate::_fromgmi () {
     test -z "title" && title=$SUBTITLE
     $SED -i "s|%%TITLE%%|$title|g" "$dest.tmp"
     mv "$dest.tmp" "$dest"
+
     test "$USE_GIT" == yes && git::add "$format" "$dest"
 }
 
@@ -141,9 +144,9 @@ generate::fromgmi () {
         git::commit gemtext "$GIT_COMMIT_MESSAGE"
         git::commit meta "$GIT_COMMIT_MESSAGE"
     fi
+
     for format in "$@"; do
         test "$USE_GIT" == yes && git::commit "$format" "$GIT_COMMIT_MESSAGE"
         log INFO "$format can be found in $CONTENT_BASE_DIR/$format now"
     done
-
 }