From b73fc8e831806abf6432e5e443834e94c70dd4e7 Mon Sep 17 00:00:00 2001
From: Jasper Van der Jeugt <jaspervdj@gmail.com>
Date: Sat, 26 Feb 2011 11:07:46 +0100
Subject: Add some more information on metacompilation
---
examples/hakyll/tutorial.markdown | 10 ++++++++--
src/Hakyll/Core/Rules.hs | 21 ++++++++++++++++++++-
2 files changed, 28 insertions(+), 3 deletions(-)
diff --git a/examples/hakyll/tutorial.markdown b/examples/hakyll/tutorial.markdown
index 4596739..642c4f2 100644
--- a/examples/hakyll/tutorial.markdown
+++ b/examples/hakyll/tutorial.markdown
@@ -150,7 +150,8 @@ later[^1].
template compile rule at the bottom -- this would make no difference.
Now, it's time to actually render our pages. We use the `forM_` monad combinator
-so we can describe all files at once.
+so we can describe all files at once (instead of compiling all three files
+manually).
~~~~~{.haskell}
forM_ ["about.rst", "index.markdown", "code.lhs"] $ \page -> do
@@ -170,7 +171,7 @@ DSL there.
The gist of it is that the `Compiler a b` type has two parameters -- it is an
Arrow, and we can chain compilers using the `>>>` operator. The [compiler]
-reference page has some more information on this subject.
+reference page has some more readable information on this subject.
[compiler]: /reference/Hakyll-Core-Compiler.html
@@ -179,3 +180,8 @@ compile page $ pageCompiler
>>> applyTemplateCompiler "templates/default.html"
>>> relativizeUrlsCompiler
~~~~~
+
+Note that we can only use `applyTemplateCompiler` with
+`"templates/default.html"` because we compiled `"templates/default.html"`. If we
+didn't list a rule for that item, the compilation would fail (Hakyll would not
+know what `"templates/default.html"` is!).
diff --git a/src/Hakyll/Core/Rules.hs b/src/Hakyll/Core/Rules.hs
index 1aa3ad3..eba3fb9 100644
--- a/src/Hakyll/Core/Rules.hs
+++ b/src/Hakyll/Core/Rules.hs
@@ -81,7 +81,9 @@ compile pattern compiler = RulesM $ do
-- | Add a compilation rule
--
-- This sets a compiler for the given identifier. No resource is needed, since
--- we are creating the item from scratch.
+-- we are creating the item from scratch. This is useful if you want to create a
+-- page on your site that just takes content from other items -- but has no
+-- actual content itself.
--
create :: (Binary a, Typeable a, Writable a)
=> Identifier -> Compiler () a -> Rules
@@ -98,6 +100,23 @@ route pattern route' = tellRoute $ ifMatch pattern route'
-- Metacompilers are a special class of compilers: they are compilers which
-- produce other compilers.
--
+-- This is needed when the list of compilers depends on something we cannot know
+-- before actually running other compilers. The most typical example is if we
+-- have a blogpost using tags.
+--
+-- Every post has a collection of tags. For example,
+--
+-- > post1: code, haskell
+-- > post2: code, random
+--
+-- Now, we want to create a list of posts for every tag. We cannot write this
+-- down in our 'Rules' DSL directly, since we don't know what tags the different
+-- posts will have -- we depend on information that will only be available when
+-- we are actually compiling the pages.
+--
+-- The solution is simple, using 'metaCompile', we can add a compiler that will
+-- parse the pages and produce the compilers needed for the different tag pages.
+--
-- And indeed, we can see that the first argument to 'metaCompile' is a
-- 'Compiler' which produces a list of ('Identifier', 'Compiler') pairs. The
-- idea is simple: 'metaCompile' produces a list of compilers, and the
--
cgit v1.2.3