Support more slots, including custom slotting

[Shrine-XSLT] / README.markdown
diff --git a/README.markdown b/README.markdown

index 216d4d87e4f8141c1811a6bed5b4917024bbe18e..00dd2b59aa4d6f1cf7d192870d6b1367a9ebb5d3 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -7,16 +7,14 @@ substantially changing the authoring flow.
  ## Features
  
  - Really simple shrine generation
  ## Features
  
  - Really simple shrine generation
-
  - One command: `make`
  
  ## Prerequisites
  
  - One command: `make`
  
  ## Prerequisites
  
-These things come preinstalled on many platforms :—
-
-- G·N·U Make (run `make --version` to see if it is installed)
+These things come pre·installed on many platforms :—
  
  
-- libxslt (run `xsltproc --version` to see if it is installed)
+- G·N·U `make` (run `make --version` to see if it is installed)
+- `xsltproc` (run `xsltproc --version` to see if it is installed)
  
  You will also need to know how to write X·M·L, and how to navigate to a
  directory via the command line and run `make`.
  
  You will also need to know how to write X·M·L, and how to navigate to a
  directory via the command line and run `make`.
@@ -48,43 +46,51 @@ page. The `<shrine-header>`, `<shrine-content>`, and `<shrine-footer>`
  elements will be replaced by the page header, content, and footer,
  respectively.
  
  elements will be replaced by the page header, content, and footer,
  respectively.
  
-Finally, just run `make` from this directory, and X·H·T·M·L files
+Finally, just run `make` from this directory, and H·T·M·L files
  corresponding to your source files will be created in the `public/`
  directory (which you can then serve statically from your server).
  
  corresponding to your source files will be created in the `public/`
  directory (which you can then serve statically from your server).
  
-## Notes
+## Atom Feeds
+
+Any `.atom` files you provide will automatically be filled out with
+`<id>`s, `<updated>` values, and other necessary information before
+being copied to the destination location. If you wish to use this
+feature, you will need to provide a `BASEIRI` variable when you run
+`make` to allow the X·S·L·T to transform relative links into absolute
+ones.
+
+It is recommended that :—
  
  
-- The created files have a `.xhtml` extension and *need* to be served
-  with a `application/xhtml+xml` (or `application/xml`) media type. Not
-  all servers know how to serve `.xhtml` files; if this is you, you may
-  have better luck with `make XHTMLEXT=xml` (which will produce `.xml`
-  files instead).
+- You do *not* provide your own `<id>`s and rely on the generated ones
+  (which will be an `oai:` URI derived from the file path).
  
  
-  - Some free hosting options require that “index” pages have an
-    extension of `.html`; these will unfortunately not work. It is
-    possible to extend the makefile to generate `index.html` redirects
-    to `index.xhtml` with the following code :—
+- You *do* manually provide `<updated>` times for individual entries
+  (although not the feed as a whole); otherwise every entry will be
+  marked as updated every time the feed is generated.
  
  
-    ```make
-    override redirects := $(patsubst public/%.$(XHTMLEXT),public/%.html,$(indices) $(pages))
+- All `<link rel="alternate">` elements in `<entry>` elements use a
+  relative `@href` with a leading slash. This should point to the
+  *final* location of the entry (within, but not including, `public/`).
  
  
-    all: $(redirects) # in addition to the previously declared prerequisites
+There’s an example `feed.atom` provided so you can see what this
+  feature might look like in practice.
  
  
-    $(redirects):
-       # You may want a more involved redirect page than this, but it’s an example…
-       echo '<!DOCTYPE html><meta http-equiv="refresh" content="0;url=./index.xhtml">' > $@
-    ```
+## Notes
  
  
-    This should be considered a last resort, but it can be used to get
-    your site working on e·g Neocities.
+- The created files have a `.html` extension and need to be served
+  with a `text/html` media type.
  
  - Files at `sources/index.xml` and `sources/index-*.xml` will produce
  
  - Files at `sources/index.xml` and `sources/index-*.xml` will produce
-  output at `public/%.xhtml` (where `%` is the filename).
+  output at `public/%.html` (where `%` is the filename).
  
  - All other files at `sources/*.xml` and `sources/*/*.xml` will produce
  
  - All other files at `sources/*.xml` and `sources/*/*.xml` will produce
-  output at `public/%/index.xhtml` (where `%` is the filename and
+  output at `public/%/index.html` (where `%` is the filename and
    optional subdirectory). Only one level of subdirectory is supported.
  
    optional subdirectory). Only one level of subdirectory is supported.
  
+- For any files at `sources/*.xml` and `sources/*/*.xml`, files in the
+  folder with the same name (minus the `.xml`) will be copied over
+  verbatim.
+
  - The transformation doesn’t do any rewriting of links. Make sure you
    write them to point to the *final* location of the files, not their
    location within the `sources/` directory.
  - The transformation doesn’t do any rewriting of links. Make sure you
    write them to point to the *final* location of the files, not their
    location within the `sources/` directory.
@@ -94,10 +100,21 @@ directory (which you can then serve statically from your server).
    (`<html>`) element of the template, as will `@lang` and `@xml:lang`.
    You can use this to help configure page‐specific styling.
  
    (`<html>`) element of the template, as will `@lang` and `@xml:lang`.
    You can use this to help configure page‐specific styling.
  
-- You can insert content into the `<head>` of the template by setting
-  `@slot="shrine-head"` on the appropriate elements. For example, one
-  might customize the title of a page like
-  `<title slot="shrine-head">My Title | My Cool Shrine</title>`.
+- You can use the `@slot` attribute with a few special values to insert
+  content in various places :—
+
+  - `@slot="shrine-head"` will place the content into the `<head>` of
+    the resulting document. This is especially useful for `<title>`,
+    `<meta>`, and `<style>` elements.
+
+  - For `shrine-header` and `shrine-footer`, there are `-before` and
+    `-after` slot names which will place content into the beginning or
+    ending of the shrine header or footer, respectively.
+
+  - You can define your own slots with `<slot>` in templates, headers,
+    and footers; this will enable a corresponding `@slot` name
+    beginning with `shrine-template-slot-`, `shrine-header-slot-` or
+    `shrine-footer-slot`, respectively.
  
  - If you delete files from `sources/`, the corresponding files in
    `public/` will **not** be deleted and will need to be manually
  
  - If you delete files from `sources/`, the corresponding files in
    `public/` will **not** be deleted and will need to be manually