Update documentation

doc/kiln.1.scd

@@ -2,39 +2,80 @@ kiln(1)
 
 # NAME
 
-kiln - a simple static site generator for Gemini sites
+kiln - a simple static site generator
 
 # SYNOPSIS
 
-_kiln_ [--html]
+_kiln_ [-c <config>] [-t <task>]
 
 # OPTIONS
 
-\--format <format>
+\-c <config>
-	Specifies the output format to use. Supported formats include gemini and html. Defaults to "gemini".
+	Specifies the configuration file to use. Defaults to "config.toml".
 
-# SITE STRUCTURE
+\-t <task>
+	Specifies the task to run. Defaults to "all", which runs all tasks.
 
-A kiln site is structured in the following way:
+# OVERVIEW
+
+A kiln site is built in one or more steps called _tasks_.
+
+There is only one default task called "gemini" which builds a Gemini site.
+
+The following directories are used by default:
 
 [[ *Directory*
 :[ *Description*
 |  content/
-:  Site source
+:  Content directory
+|  static/
+:  Static content directory
 |  templates/
-:  Site templates
+:  Template directory
 |  public/
-:  Site destination
+:  Output directory
 
-All files in the source directory will be copied to the destination directory.
+Tasks can be configured to use different static content and output directories.
-If the file is a Gemini file, it will be passed through a template and the result will be written to the destination directory.
+The content and template directories are shared between tasks.
-Any file or directory whose name begins with "\_" will be ignored.
 
-# TEMPLATES
 
-kiln looks for templates in the *templates* directory.
+# CONFIGURATION
-Templates use the Go templating language.
+
-The following templates are supported:
+The configuration file uses the _TOML_ configuration file format. For more
+information on TOML, see https://toml.io/en/v0.4.0.
+
+The following keys are supported:
+
+[[ *Key*
+:[ *Description*
+|  title
+:  Site title
+|  urls
+:  A list of site URLs
+
+Site URLs may contain paths, but should not end with a trailing slash. Multiple
+site URLs may be specified for sites that are available at multiple locations.
+
+## CONTENT DIRECTORY
+
+The content directory contains content that should be processed before
+being published. Any file or directory whose name begins with "\_" will be
+ignored.
+
+Files in the content directory may be preprocessed, run through templates, and
+postprocessed (in that order). Each operation takes the output of the last
+operation as input.
+
+## STATIC CONTENT DIRECTORY
+
+All files in the static content directory will be copied to the output
+directory without modification. Static assets like images should be stored in
+this directory.
+
+## TEMPLATE DIRECTORY
+
+The template directory contains templates for use when building the site.
+Templates use the Go templating language. The following templates are supported:
 
 [[ *Template*
 :[ *Description*
@@ -44,13 +85,17 @@ The following templates are supported:
 :  Directory index template
 |  atom.xml
 :  Atom feed template
-|  output.html
-:  HTML output template
 
-The scope of a template is limited to the directory it is placed in.
+The scope of a template is limited to the directory it is placed in. For
-For example, the template templates/blog/page.gmi will only apply to pages in src/blog.
+example, the template templates/blog/page.gmi will only apply to pages in
+content/blog.
 
-kiln has default templates built-in. To override the default templates, put templates in the templates/\_default directory. These templates will apply to any directory which does not have its own templates specified.
+kiln has default templates built-in. To override the default templates, put
+templates in the templates/\_default directory. These templates will apply to
+any directory which does not have its own templates specified.
+
+For more information on the Go templating language, see
+https://golang.org/pkg/text/template/.
 
 ## FUNCTIONS
 
@@ -63,7 +108,7 @@ All templates have the following functions available to them:
 
 ## SITE METADATA
 
-Site metadata contains the following information:
+Site metadata contains the following data:
 
 [[ *Variable*
 :[ *Description*
@@ -76,7 +121,7 @@ To configure these variables, see *CONFIGURATION*.
 
 ## PAGE TEMPLATES
 
-Page templates are provided with the following information:
+Page templates are provided with the following data:
 
 [[ *Variable*
 :[ *Description*
@@ -89,16 +134,17 @@ Page templates are provided with the following information:
 |  Content
 :  The contents of the page
 
-Pages can specify dates in their filenames.
+Pages can specify dates in their filenames. For example, the file
-For example, src/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a date of November 20, 2020.
+content/2020-11-20-Hello-world.gmi will have a path of /Hello-world/ and a date
+of November 20, 2020.
 
-Pages can specify a title in a top-level heading line.
+Pages can specify a title in a top-level heading line. The heading must be the
-The heading must be the first line in the page, and can optionally be followed by a blank line.
+first line in the page, and can optionally be followed by a blank line. Both
-Both lines will be removed from the page content.
+lines will be removed from the page content.
 
 ## INDEX TEMPLATES
 
-Index templates are provided with the following information:
+Index templates are provided with the following data:
 
 [[ *Variable*
 :[ *Description*
@@ -113,14 +159,23 @@ Index templates are provided with the following information:
 |  Dirs
 :  List of subdirectories
 
-The title and content are taken from the index.gmi file in the directory.
+The title and content are taken from the index.gmi file in the directory. If no
-If no index.gmi file exists, then the index template will not be rendered.
+index.gmi file exists, then the index template will not be rendered.
 
-The default index template implements the lightweight subscription specification found at gemini://gemini.circumlunar.space/docs/companion/subscription.gmi.
+The default index template implements the lightweight subscription specification
+found at gemini://gemini.circumlunar.space/docs/companion/subscription.gmi.
+
+## FEEDS
+
+Feeds can optionally be specified in the *feeds* table of the configuration file.
+Keys denote the path to the feed input directory and values denote the title of
+the feed.
+
+Feeds are written to the directory path plus "atom.xml".
 
 ## FEED TEMPLATES
 
-Atom feed templates are provided with the following information:
+Feed templates are provided with the following data:
 
 [[ *Variable*
 :[ *Description*
@@ -131,48 +186,5 @@ Atom feed templates are provided with the following information:
 |  Entries
 :  List of pages in this feed
 
-Feeds are written to the directory path plus "atom.xml".
+The default feed template uses the site URLs, if any, to turn relative links
-
+into absolute URLs.
-The default feed template uses the site URLs, if present, to make relative links into absolute URLs.
-
-## HTML TEMPLATES
-
-HTML output templates are provided with the following information:
-
-[[ *Variable*
-:[ *Description*
-|  Title
-:  Title of the page
-|  Content
-:  HTML contents of the page
-
-# CONFIGURATION
-
-kiln looks for a configuration file named "config.ini".
-
-The configuration file uses the _ini_ format.
-A line beginning with ";" is considered a comment and ignored, as are empty lines.
-New sections begin with [section-name] on a single line.
-Keys and values are separated with "=".
-
-The following keys are supported:
-
-[[ *Key*
-:[ *Description*
-|  title
-:  Site title
-|  url
-:  One or more site URLs separated by whitespace.
-
-Site URLs are used when generating Atom feeds.
-Site URLs may contain paths, but should not end with a trailing slash.
-Multiple site URLs may be specified if they are separated by whitespace.
-This allows a site that is hosted on both Gemini and HTTP to specify URLs for both locations.
-
-The following sections are supported:
-
-[[ *Section*
-:[ *Description*
-|  feeds
-:  A list of Atom feeds. Keys denote the path to the feed directory, and values denote the title of the feed.
-