From b73fc8e831806abf6432e5e443834e94c70dd4e7 Mon Sep 17 00:00:00 2001 From: Jasper Van der Jeugt 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