documentation

1 files changed, 97 insertions, 0 deletions

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..d373438
--- /dev/null
+++ b/README.org
@@ -0,0 +1,97 @@
+* Directory layout
+
+Here's the gist:
+
+ - ~/src/~ : website content
+ - ~/bin/~ : programs and such for generating the website from ~/src/~
+ - ~/out/~ : where the generated output goes
+ - ~/Makefile~ : invoke ~/bin/~ as appropriate
+ - ~/git-setup~ : set up git hooks (see below)
+ - ~/benchmark~ : runs ~make~ and reports how long each part took
+
+The web server should serve the union of ~/src/~ and ~/out/~.
+
+On the ~master~ branch, ~/out/~ is ignored.  But ~git-setup~ will set
+up a git post-commit hook to generate ~/out/~ and commit it to the
+~pre-generated~ branch.
+
+* Document metadata
+
+Currently supported are Markdown (~.md~) and Org-mode (~.org~) files.
+Each of these format supports embedding metadata in the document
+(well, Markdown doesn't really, but the Pandoc syntax extension
+~yaml_metadata_block~ adds it).
+
+In Org-mode, this looks like
+
+#+BEGIN_SRC
+#+KEY: value
+
+...rest of document...
+#+END_SRC
+
+In Markdown, this looks like
+
+#+BEGIN_SRC
+---
+key: value
+key2:
+ - any YAML values
+---
+
+...rest of document...
+#+END_SRC
+
+AFAIK, unfortunately Org-mode only has values as strings, no
+structured data.
+
+Pandoc may make use of some of these values internally when converting
+to HTML.  See the Org-mode and Pandoc documentation.
+
+However, there are some of these that are used specially by the site
+generator:
+
+| attribute       | default                         | standard           | format                                     |
+|-----------------+---------------------------------+--------------------+--------------------------------------------|
+| title           | the first line of the file      | Pandoc             | string                                     |
+| author          | "Andrew Murrell"                | Pandoc             | string or list                             |
+| license         | "CC BY-SA-3.0"                  | no                 | string                                     |
+| pandoc_flags    | ""                              | no                 | string ("--foo --bar")                     |
+| pandoc_format   | either "markdown" or "org"      | no                 | string ("markdown+extnsn1+extnsns2")       |
+| html_head_extra | ""                              | Org-mode           | string                                     |
+| tags            | ""                              | LaTeX, kinda[fn:1] | string ("ES HB") or list (["ES", "HB"])    |
+| published[fn:2] | most recent git commit for file | no                 | string (Ruby ~Date.parse()~) or date[fn:3] |
+| updated[fn:2]   | first git commit for file       | no                 | string (Ruby ~Date.parse()~) or date[fn:3] |
+
+[fn:1] The ~tags~ attribute is normally a list, but because I don't
+know how to do a list in Org-mode, I made it take a
+whitespace-separated string as well.
+
+[fn:2] The "published"/"updated" terminology is borrowed from the Atom
+specification (RFC 4287), and I intend them to have the same
+semantics.  The "standard" variable name is "date", but I thought that
+was dreadfully ambiguous and confusing when the site generator deals
+with two distinct dates.
+
+[fn:3] At various times there have been bugs in the YAML parser
+library that Pandoc uses, causing it to fail to parse dates, so I just
+always put the date in quotes now, and let Ruby ~Date.parse()~ take
+care of it.
+
+* Make targets
+
+ - ~all~ (default) : generate all generated files
+ - ~serve~ : alias for ~serve-8000~
+ - ~serve-PORTNUMBER~ : Run an HTTP server on PORTNUMBER.  Search
+   won't work.
+
+* Make dependencies
+
+ - ~all~
+   - GNU Make
+   - Ruby
+   - Pandoc 1.17+
+   - scss
+ - ~serve-%~ (in addition to what is needed for ~all~)
+   - unionfs
+   - python3