[Haskell-cafe] Re: ANN: diagrams 0.2

[Gwern Branwen]

On Sat, Jan 31, 2009 at 6:45 PM, Brent Yorgey <byorgey at seas.upenn.edu> wrote:
> On Sat, Jan 31, 2009 at 06:23:29PM -0500, Braden Shepherdson wrote:
>> Brent Yorgey wrote:
>>> I am very pleased to announce the 0.2 release of the diagrams package,
>>
>> Would this make a handy plugin for gitit? I'm currently putting diagrams
>> together in xfig and saving them to my gitit tree while taking notes in
>> gitit, but being able to write diagrams code into gitit would be great.
>>
>> How easy or hard would this be to accomplish?
>
> Well, the short answer is: I think diagrams would be very well-suited
> to this, and the difficulty probably depends more on gitit than
> diagrams.  Perhaps someone who knows more about gitit can speak to
> this as well.

/me looks around. oh.

> In theory, it should be easy to write a plugin which takes some
> Haskell code defining a top-level binding 'dia' (or something similar)
> of type Diagram, wraps it in some appropriate imports and an
> appropriate one-line definition for main, then compiles and runs it in
> a sandbox and sticks the generated image in the wiki output. The
> devil's in the details, of course: you'd probably want to cache the
> generated images indexed by a hash of the diagrams code that generated
> them, to avoid recomputing the image every time the page loads.  And
> there are probably other considerations I'm not thinking of.
>
> -Brent

As it happens, I recently got interested in plugins for Gitit/Pandoc
since they're the most straightforward way to implement features I
would like very much*. John discussed it briefly:
http://groups.google.com/group/pandoc-discuss/browse_thread/thread/54272f922c80b7b0

The crucial part is the definition processWith & processWithM:

processWith :: (Data a, Data b) => (a -> a) -> b -> b
processWithM :: (Monad m, Data a, Data b) => (a -> m a) -> b -> m b

If I understand Braden, he wants to write down some Haskell expression
and see instead whatever image is generated. So suppose we have syntax
like this:

!!!! Basic Circle
draw $ circle 50 10
!!!!

We toss into gitit a call to 'processWith imageGenerator'.
imageGenerator looks something like

imageGenerator a = unsafePerformIO $ do expr <- filterPlugins a
                                          img <- Diagrams.run expr
                                          writeFile path img
                                          replace a ("![](" ++ path ++ ")")
                                     where path = "static/user/" ++
"Basic Circle.png"

Obviously this is just pseudocode, as 'replace' and 'filterPlugins'
are nontrivial to write, but you get the idea. We stream through the
wikitext looking for our special symbols which denote Diagram code,
then we pass it to Diagrams (I handwave over how to turn String into a
function suitable for Diagrams - maybe this would be actually a call
to a Diagram executable?), save the image to a known location, and
then replace the Diagram code with the Markdown syntax for
linking/including an image.

I doubt I'll do this anytime soon, but I suspect that with this
approach, such a plugin would be about an evening's work or so.

* signatures, interwiki links, and possibly categories

-- 
gwern