Few changes to 05-snapshots... to complete the instructions.

[why-not-try-calmer]

Fixed very small gaps in the instructions.

[Minoru]

I think the tutorial is short and simple enough that the reader doesn't need all the code repeated at the end. Thanks for the work, sorry I won't merge this!

[why-not-try-calmer]

I think the tutorial is short and simple enough that the reader doesn't need all the code repeated at the end. Thanks for the work, sorry I won't merge this!

Thanks, I think you didn't get an important point, which is that the tutorial is incomplete: following the tutorial will not get the user to build the target .xml file. This is a severe shortcoming which, I think you'll admit, deserves to be addressed, which is what this PR does.

I am given to understand that you find the fixed tutorial too long. It's however quite trivial to fix. See #942.

[Minoru]

I followed the tutorial and got the .xml file:

$ mkdir demo
$ cd demo
$ hakyll-init .

# I picked this snapshot to save time, as I already have Hakyll built from it
$ stack init --resolver=lts-19.0

$ cat > site.hs
{-# LANGUAGE OverloadedStrings #-}
import           Data.Monoid (mappend)
import           Hakyll

myFeedConfiguration :: FeedConfiguration
myFeedConfiguration = FeedConfiguration
    { feedTitle       = "Healthy cooking: latest recipes"
    , feedDescription = "This feed provides fresh recipes for fresh food!"
    , feedAuthorName  = "John Doe"
    , feedAuthorEmail = "[email protected]"
    , feedRoot        = "http://healthycooking.example.com"
    }

main :: IO ()
main = hakyll $ do
    match "templates/*" $ compile templateBodyCompiler

    create ["atom.xml"] $ do
        route idRoute
        compile $ do
            let feedCtx = postCtx `mappend`
                    constField "description" "This is the post description"

            posts <- fmap (take 10) . recentFirst =<< loadAll "posts/*"
            renderAtom myFeedConfiguration feedCtx posts

    match "posts/*" $ do
        route $ setExtension "html"
        compile $ pandocCompiler
            >>= loadAndApplyTemplate "templates/post.html"    postCtx
            >>= saveSnapshot "content" -- new
            >>= loadAndApplyTemplate "templates/default.html" postCtx
            >>= relativizeUrls

postCtx :: Context String
postCtx =
    dateField "date" "%B %e, %Y" `mappend`
    defaultContext

$ stack run -- rebuild
Building all executables for `demo' once. After a successful build of all of them, only specified executables will be rebuilt.
demo> configure (exe)
Configuring demo-0.1.0.0...
demo> build (exe)
Preprocessing executable 'site' for demo-0.1.0.0..
Building executable 'site' for demo-0.1.0.0..
[1 of 1] Compiling Main
Linking .stack-work/dist/x86_64-linux-tinfo6/Cabal-3.4.1.0/build/site/site ...
demo> copy/register
Installing executable site in /dev/shm/demo/.stack-work/install/x86_64-linux-tinfo6/864ae7271f046b5e971924514cb85ad8fda36e70b25dbc7c638bccac862df299/9.0.2/bin
Removing _site...
Removing _cache...
Removing _cache/tmp...
Initialising...
  Creating store...
  Creating provider...
  Running rules...
Checking for out-of-date items
Compiling
  updated templates/archive.html
  updated templates/post-list.html
  updated templates/default.html
  updated templates/post.html
  updated posts/2015-08-12-spqr.markdown
  updated posts/2015-11-28-carpe-diem.markdown
  updated posts/2015-10-07-rosa-rosa-rosam.markdown
  updated posts/2015-12-07-tu-quoque.markdown
  updated atom.xml
Success

Am I missing something here?

[why-not-try-calmer]

Am I missing something here?

Yup. Or better said: you're are adding an extra bit which is absent from the tutorial (I am referring to its web rendering): a call site for the (body of) the unamed function:

create ["atom.xml"] $ do
    route idRoute
    compile $ do
        let feedCtx = postCtx `mappend` bodyField "description"
        posts <- fmap (take 10) . recentFirst =<<
            loadAllSnapshots "posts/*" "content"
        renderAtom myFeedConfiguration feedCtx posts

Adding stuff that's not explicit in tutorials happens when you know what you're doing. But I think it's a nice move to new users to offer them explicitness when possible -- especially users who might not be very comfortable with Haskell.

The PR is now closed, but see #942.

[Minoru]

Calling create is explained in part three of the tutorial. Sorry, I don't think the problem you're trying to fix here exists, so please close #942 — I won't merge it either.

[why-not-try-calmer]

Calling create is explained in part three of the tutorial. Sorry, I don't think the problem you're trying to fix here exists, so please close #942 — I won't merge it either.

Can you show me exactly where you see the tutorial tell the user about the call site for create?

Of course, here we are talking about https://jaspervdj.be/hakyll/tutorials/05-snapshots-feeds.html. If what you have in mind is https://jaspervdj.be/hakyll/tutorials/03-rules-routes-compilers.html, featuring indeed the sentence:

However, we can see that one item makes no use of match, but uses create instead.

that's a completely different tutorial, and it would be more user friendly to not assume that they have read it before reading the tutorial about snapshots (unless there is a mention somewhere that tutorials should be read in order).

[Minoru]

Yes, I had the third part in mind. The fact that they should be read in order can be derived from how they're titled on the "Tutorials" page: "Tutorial series".

[why-not-try-calmer]

@jaspervdj Sorry to ping you but I'd like to hear your opinion on this. To me all this sounds like making things unnecessarily complicated for new users, which may or may not be familiar with Haskell, and may be at various degree. I do not understand why making things explicit is worse than making them implicit.

I also take note of the fact that https://jaspervdj.be/hakyll/tutorials/03-rules-routes-compilers.html does not really address the problem, as it does not make it explicit the call site for create.