From e92c82e2c9ff541cd321ad7a8aedcf34e615197c Mon Sep 17 00:00:00 2001 From: Lars-Dominik Braun Date: Sun, 14 Jun 2015 20:35:08 +0200 Subject: First public version --- src/Codec/Pesto.lhs | 187 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) create mode 100644 src/Codec/Pesto.lhs (limited to 'src/Codec/Pesto.lhs') 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 `_ motivates why inventing another file format is +necessary, followed by the goals_ of Pesto. After a short Pesto `primer +`_ intended for the casual user the language’s +`syntax `_ and `semantics `_ are +presented. The `linting section `_ limits the language to useful +cooking recipes. Examples for user presentation of recipes and serialization +follow. + +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: http://learnyouahaskell.com/ +.. _HUnit: http://hackage.haskell.org/package/HUnit +.. _parsec: http://hackage.haskell.org/package/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: http://tools.ietf.org/html/rfc2119 + +:Version: 1-draft +:License: CC0_ +:Website: https://6xq.net/pesto/ +:Discussion: https://github.com/PromyLOPh/pesto +:Contributors: + - `Lars-Dominik Braun `_ + +.. _CC0: https://creativecommons.org/publicdomain/zero/1.0/ + +.. _motivation: + +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: https://developers.google.com/structured-data/rich-snippets/recipes +.. _schema.org: http://schema.org/Recipe +.. _h-recipe: http://microformats.org/wiki/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 +Mastercook. + +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 +license. +`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: https://creativecommons.org/licenses/by-sa/2.5/ + +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: http://reml.sourceforge.net/ +.. _RecipeML: http://www.formatdata.com/recipeml/index.html +.. _CookML: http://www.kalorio.de/index.php?Mod=Ac&Cap=CE&SCa=../cml/CookML_EN +.. _Mealmaster: http://www.wedesoft.de/anymeal-api/mealmaster.html +.. _MXP: http://www.oocities.org/heartland/woods/2073/Appendix.htm +.. _RecipeBook XML: http://web.archive.org/web/20141101132332/http://www.happy-monkey.net/recipebook/ +.. _YumML: http://web.archive.org/web/20140703234140/http://vikingco.de/yumml.html +.. _Rezkonv: http://www.rezkonv.de/software/rksuite/rkformat.html +.. _RxOL: http://www.dodomagnifico.com/641/Recipes/CompCook.html +.. _Gourmet: http://thinkle.github.io/gourmet/ +.. _KRecipes: http://krecipes.sourceforge.net/ + +.. There is a copy at http://diyhpl.us/~bryan/papers2/CompCook.html as well + +.. More interesting stuff: +.. - http://blog.moertel.com/posts/2010-01-08-a-formal-language-for-recipes-brain-dump.html +.. - http://www.dangermouse.net/esoteric/chef.html + +Goals +----- + +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 +`_ 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: https://daringfireball.net/projects/markdown/syntax + +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 +books. + +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 https://github.com/PromyLOPh/rezepte 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? + -- cgit v1.2.3