[Haskell-cafe] Help starting a Haskell blog

[Jeremy Shaw]

Hello,

What I do is I write my blog posts using a literate Haskell +
html. This allows me to actually run all the code and make sure it
works. I can then use hscolour to transform the literal Haskell into
html (with syntax highlighting).

As a reader, I think you imagine that I have two distinct things:

 1. some application I have written with comments, etc
 2. a blog post I have written about the app, by copying and pasting the code into the blog post

But, having two copies of the code in play is tricky. Instead I have a
single set of source, and I generate the normal looking code and the
blog post from the same source. This ensures that everything stays
in-sync. So, I actually have three things going on:

 1. a literate Haskell document which contains the source code, the
 blog post markup, and is directly executable. I can load this
 document directly into GHCi while I work on it -- no extra steps
 required.

From that literate document I generate:

 2. a blog post where all the source code has been highlighting via
 HsColour. The non-source parts are just the HTML I wrote in the
 literate comments. 

 3. a plain old Haskell code version of my codebase which includes
 Haskell comments, but none of the literate comments.


This post:

http://nhlab.blogspot.com/2008_07_01_archive.html

was generated from this source:

darcs get http://src.seereason.com/examples/happs-hsp-quickstart/

running 'make' will generate the html which can be copied into the
blog posting form. 

running 'make test' will actually run the literate code.

running 'make template' will produce a non-literate version of the
code base in the template directory.

The following 'tricks' are used:

 1. use cpp and #ifdef HsColour, so that some bits of code get syntax
 highlighting, but aren't compiled when you actually run the literate
 Haskell.

 2. If your application is spread across multiple modules, you can use:

#ifdef HsColour
#include "SimpleExample.lhs"
#endif

  to merge all the dependent modules into a single .html file.

 3. Sometimes in a blog post you want to show multiple interations of
 a function. But, you can't reuse the same name because you get name
 collisions, so you have to keep renaming the function as you talk
 about it:

  myfunc = ...

  myfunc' = ...

  myfunc'' = ...

 sometimes you can work around this by putting each iteration in a separate file,


#ifdef HsColour
#include "MyFunc1.lhs"
#endif

#ifdef HsColour
#include "MyFunc2.lhs"
#endif

#ifdef HsColour
#include "MyFunc3.lhs"
#endif

 You can then run each version independently in ghci to test them, but
 they will all be included in the master .html file.

 4. The following targets run the preprocessor and then invoke HsColour with the correct arguments for turning code parts into html while preserving the existing html in the literate comments:

%.html: %.cpphs
	HsColour -css $< -o$@ -lit
	validate -w --verbose --emacs $@


%.cpphs: %.lhs
	cpp -traditional-cpp -DHsColour -P $< $@

 5. this target can be used to extract just the non-literate parts from the .lhs 

%.hs: %.lhs
	sed -n 's/^> \?//p' $^ > $@

 6. hide the pre-processor option

In order to be able to load the .lhs files into GHCi, the preprocessor
needs to run. But, that is just a side effect of this blogging system,
so I don't want the pragma for running cpp to show up in the blog post
itself. This turns out to be a bit tricky. The work around is to
enable the cpp flag inside an HTML comment, so that the option is
enabled, but the user doesn't see it:

<!--

> {-# OPTIONS_GHC -cpp #-}

-->

 7. other

And, finally, to get the highlight code to show up highlight in
blogger, I had to modify my default blogger template to include the
css from emacs.css in the HsColour package.

I don't claim that this is the most elegant setup. It's key benefits
are that you can actually run the code in the blog post, and not worry
about copy and paste errors, or updating your code and forgetting to
update the blog post as well.

Additionally, you can automatically extract the code and non-literate
comments from the blogpost to get a nice stand alone, commented
program.

I like this approach, because as I blog about an application, I often
see improvements, bug fixes, or other changes I want to make. By
having only one copy of the code, I don't have to worry about the blog
post and code base getting out of sync.

- jeremy

p.s. That post is old and depends on a bunch of obsolete libraries, so
I would not spend anytime trying to get the Haskell code in it to
actually run. 

At Sat, 22 Aug 2009 12:35:52 +0200,
Peter Verswyvelen wrote:
> 
> [1  <multipart/alternative (7bit)>]
> [1.1  <text/plain; ISO-8859-1 (7bit)>]
> I'm going start my very first blog, documenting my everyday struggle to
> switch my old imperative mind to the lazy functional setting, with a focus
> on FRP.
> Although you can find a lot of articles that provide help to get started
> with general blogging, it might be useful to pick a blog in which presenting
> Haskell code is easy (e.g. like hpaste that does the syntax coloring for
> you), and where users can give feedback, providing code, also with syntax
> coloring preferably. It would also be nice to allow hyperlinking every
> function in the code to the standard Haskell library docs or to the docs on
> Hackage.
> 
> Googling for "how to start a Haskell blog" just revealed a lot of Haskell
> blogs.
> 
> Could you share your experiences with me about starting a blog?
> 
> BTW: I'm on Windows.
> 
> Thanks a lot,
> Peter Verswyvelen
> [1.2  <text/html; ISO-8859-1 (quoted-printable)>]
> 
> [2  <text/plain; us-ascii (7bit)>]
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe