Make everything Makefile variables which can be

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

index c7b84ae3cd306f5e925b176dc4470d1dbe3068af..93ff7c11676fd1923fed6bc22ff2aa11ab263ea6 100644 (file)
--- a/README.markdown
+++ b/README.markdown
@@ -7,7 +7,6 @@ substantially changing the authoring flow.
  ## Features
  
  - Really simple shrine generation
  ## Features
  
  - Really simple shrine generation
-
  - One command: `make`
  
  ## Prerequisites
  - One command: `make`
  
  ## Prerequisites
@@ -32,14 +31,14 @@ of these files should typically be an H·T·M·L `<article>` element
  (remember to declare the X·H·T·M·L namespace!), and you should give it
  a `@lang` attribute as well. An example is provided.
  
  (remember to declare the X·H·T·M·L namespace!), and you should give it
  a `@lang` attribute as well. An example is provided.
  
-The `@data-shrine-header` and `@data-shrine-footer` attributes on the
-root elements of your pages specify the names of the header and footer
-to use on the page. You can use headers and footers to supply page
-navigation, branding, and so forth. For each header and footer you
-specify, you will need to create a corresponding `$-header.xml` or
-`$-footer.xml` (where `$` is the header/footer name) which provides
-the contents. These files should be placed in *this* (repository root)
-directory, not in `sources/`.
+The (entirely optional) `@data-shrine-header` and `@data-shrine-footer`
+attributes on the root elements of your pages specify the names of the
+header and footer to use on the page. You can use headers and footers
+to supply page navigation, branding, and so forth. For each header and
+footer you specify, you will need to create a corresponding
+`$-header.xml` or `$-footer.xml` (where `$` is the header/footer name)
+which provides the contents. These files should be placed in *this*
+(repository root) directory, not in `sources/`.
  
  The `template.xml` file in this directory contains the main page
  template, and you should edit it to add styling and so forth to your
  
  The `template.xml` file in this directory contains the main page
  template, and you should edit it to add styling and so forth to your
@@ -51,7 +50,54 @@ 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
+## Advanced Features
+
+### Slots
+
+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.
+
+### Microdata
+
+You can use the H·T·M·L `@itemprop` attribute to define metadata for
+your site pages. The following values are supported :—
+
+- `shrine-title`: The title of the page.
+
+- `shrine-id`: A persistent, globally‐unique identifier for the page.
+
+- `shrine-updated`: The datetime that the page was last updated.
+
+Multiple values for a single `@itemprop` are not currently supported.
+Where possible, X·M·L markup will be preserved when accessing metadata
+values.
+
+### 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.
+
+There’s an example `feed.atom` provided so you can see what this
+feature might look like in practice.
+
+## Additional Notes
  
  - The created files have a `.html` extension and need to be served
    with a `text/html` media type.
  
  - The created files have a `.html` extension and need to be served
    with a `text/html` media type.
@@ -63,6 +109,10 @@ directory (which you can then serve statically from your server).
    output at `public/%/index.html` (where `%` is the filename and
    optional subdirectory). Only one level of subdirectory is supported.
  
    output at `public/%/index.html` (where `%` is the filename and
    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.
@@ -72,11 +122,6 @@ 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>`.
-
  - If you delete files from `sources/`, the corresponding files in
    `public/` will **not** be deleted and will need to be manually
    removed. An easy way to ensure that there are no outdated files in
  - If you delete files from `sources/`, the corresponding files in
    `public/` will **not** be deleted and will need to be manually
    removed. An easy way to ensure that there are no outdated files in