path: root/src/Codec/Pesto.lhs
diff options
Diffstat (limited to 'src/Codec/Pesto.lhs')
1 files changed, 187 insertions, 0 deletions
diff --git a/src/Codec/Pesto.lhs b/src/Codec/Pesto.lhs
new file mode 100644
index 0000000..c35d15f
--- /dev/null
+++ b/src/Codec/Pesto.lhs
@@ -0,0 +1,187 @@
+Pesto specification draft
+Pesto is a text-based human-editable and machine-transformable cooking recipe
+interchange format.
+.. class:: nodoc
+> module Codec.Pesto where
+About this document
+This section contains various information about this document. The `second
+section <motivation_>`_ motivates why inventing another file format is
+necessary, followed by the goals_ of Pesto. After a short Pesto `primer
+<introduction-by-example_>`_ intended for the casual user the language’s
+`syntax <language-syntax_>`_ and `semantics <language-semantics_>`_ are
+presented. The `linting section <linting_>`_ limits the language to useful
+cooking recipes. Examples for user presentation of recipes and serialization
+Being a literate program this document is specification and reference
+implementation at the same time. The code is written in Haskell_ and uses the
+parsec_ parser combinator library, as well as HUnit_ for unit tests. Even
+without knowing Haskell’s syntax you should be able to understand this
+specification. There’s a description above every code snippet explaining what
+is going on.
+.. _Haskell:
+.. _HUnit:
+.. _parsec:
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”,
+“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be
+interpreted as described in `RFC 2119`_.
+.. _RFC 2119:
+:Version: 1-draft
+:License: CC0_
+ - `Lars-Dominik Braun <>`_
+.. _CC0:
+.. _motivation:
+The landscape of recipe interchange formats is quite fragmented. First of all
+there’s HTML microdata. `Google rich snippets`_, which are equivalent to the
+schema.org_ microdata vocabulary, are widely used by commercial recipe sites.
+Although the main objective of microdata is to make content machine-readable
+most sites will probably do so, because it is considered a search-engine
+optimization (SEO). Additionally parsing HTML pulled from the web is a
+nightmare and thus not a real option for sharing recipes. h-recipe_ provides a
+second vocabulary, but has not been adopted widely.
+.. _Google rich snippets:
+.. _h-recipe:
+Mealmaster_, an ancient file format with – due to its age – many problems,
+seems to have the most traction right now. A large amount of recipe files is
+`available in this format <>`_. Rezkonv_ aims to
+improve the Mealmaster format. However the specification is available on
+request only. Another text-based format, MXP_ (plus MX2, MZ2), is used by
+A newer format, YumML_, is based on YAML. The specification has been removed
+from the web and is available through the Web Archive only.
+.. _xml-formats:
+There’s a number of XML-based formats:
+RecipeML_, formerly known as DESSERT was released in 2002 (version 0.5). The
+license requires attribution and – at the same time – forbids using the name
+RecipeML for promotion without written permission.
+REML_ was released in 2005 (version 0.5). It is rather complicated and has no
+`RecipeBook XML`_, released in 2005 as well and shared unter the terms of `CC
+by-sa`_ is not available on the web any more.
+CookML_, created in 2006 (version 1.0.4) for the german-language shareware
+program Kalorio has a custom and restrictive licence that requires attribution and
+forbids derivate works.
+KRecipes_ uses its own export format. However there is no documentation
+whatsoever. Gourmet_’s export format suffers from the same problem. The only
+document available is the `DTD
+.. _CC by-sa:
+All of the formats above share a common design aspect: They split recipes into
+two parts, ingredients and instructions. This is quite odd given the nature of
+cooking recipes. RxOL_, created in 1985, represents recipes as a graph with
+postfix notation and minimal “chitchat”. Although Pesto is not a direct
+descendant of RxOL it’s syntax and semantics are quite similar.
+.. _REML:
+.. _RecipeML:
+.. _CookML:
+.. _Mealmaster:
+.. _MXP:
+.. _RecipeBook XML:
+.. _YumML:
+.. _Rezkonv:
+.. _RxOL:
+.. _Gourmet:
+.. _KRecipes:
+.. There is a copy at as well
+.. More interesting stuff:
+.. -
+.. -
+First of all recipes are written *by* humans *for* humans. Thus a
+human-readable recipe interchange format is not enough. The recipes need to be
+human-editable without guidance like a GUI or assistant. That’s why, for
+instance, XML is not suitable and the interchange formats listed `above
+<xml-formats_>`_ have largely failed to gain traction. XML, even though simple
+itself, is still too complicated for the ordinary user. Instead a format needs
+to be as simple as possible, with as little markup as possible. A human editor
+must be able to remember the entire syntax. This works best if the file
+contents “make sense”. A good example for this is Markdown_.
+.. _Markdown:
+We also have to acknowledge that machines play an important role in our daily
+life. They can help us, the users, accomplish our goals if they are able to
+understand the recipes as well. Thus they too need to be able to read and write
+recipes. Again, designing a machine-readable format is not enough. Recipes must
+be machine-transformable. A computer program should be able to create a new
+recipe from two existing ones, look up the ingredients and tell us how many
+joules one piece of that cake will have. And so on.
+That being said, Pesto does not aim to carry additional information about
+ingredients or recipes itself. Nutrition data for each ingredient should be
+maintained in a separate database. Due to its minimal syntax Pesto is also not
+suitable for extensive guides on cooking or the usual chitchat found in cooking
+Introduction by example
+So let’s start by introducing Pesto in a XXXnon-formal, XXX way: By example. We
+are now going to cook XXX. The following recipe contains all the information
+you need to do that.
+.. class:: todo
+do it.
+See for example recipes.
+.. include:: Pesto/Parse.lhs
+.. include:: Pesto/Graph.lhs
+.. include:: Pesto/Lint.lhs
+.. include:: Pesto/Dot.lhs
+.. include:: Pesto/Serialize.lhs
+Using this project
+This project uses cabal. It provides the Codec.Pesto library that implements
+the Pesto language as described in the previous sections. It also comes with
+three binaries.
+.. include:: ../Main.lhs
+.. include:: ../Test.lhs
+.. include:: ../Doc.lhs
+Final words
+.. class:: todo
+Do we even need this?