diff options
Diffstat (limited to 'src/lib/Codec/Pesto.lhs')
| -rw-r--r-- | src/lib/Codec/Pesto.lhs | 283 |
1 files changed, 283 insertions, 0 deletions
diff --git a/src/lib/Codec/Pesto.lhs b/src/lib/Codec/Pesto.lhs new file mode 100644 index 0000000..ba8e332 --- /dev/null +++ b/src/lib/Codec/Pesto.lhs @@ -0,0 +1,283 @@ +============================ +Pesto language specification +============================ + +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__ 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. + +__ #motivation +__ #goals +__ #introduction-by-example +__ #language-syntax +__ #language-semantics +__ #linting + +Being a literate program, this document is specification and reference +implementation simultaneously. 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/ +:Source code: https://codeberg.org/ldb/pesto + +.. _CC0: https://creativecommons.org/publicdomain/zero/1.0/ + +.. _motivation: + +Motivation +---------- + +The landscape of recipe interchange formats is quite fragmented. First, +there’s HTML microdata: `Google rich snippets`_, 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 use it because it is considered a search-engine +optimization (SEO) and not a method for sharing recipes. h-recipe_ provides a +second vocabulary that has not been adopted widely yet. + +.. _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 + +.. _formats-by-software: + +Most cooking-related software comes with custom recipe file formats. Some +of them can be imported by other programs. Meal-Master_ is one of these +widely supported formats. A vast trove of recipe files is `available in +this format <http://www.ffts.com/recipes.htm>`_. There does not seem +to be any official documentation for the format, but inofficial `ABNF +grammar`_ and `format description <http://www.ffts.com/mmformat.txt>`_ +exist. A Meal-Master recipe template might look like this: + +.. _MasterCook: http://mastercook.com/ +.. _MXP: http://www.oocities.org/heartland/woods/2073/Appendix.htm +.. _ABNF grammar: http://web.archive.org/web/20161002135718/http://www.wedesoft.de/anymeal-api/mealmaster.html + +.. code:: mealmaster + + ---------- Recipe via Meal-Master (tm) + + Title: <Title> + Categories: <Categories> + Yield: <N servings> + + <N> <unit> <ingredient> + … + + -------------------------------<Section name>----------------------------- + <More ingredients> + + <Instructions> + + ----- + +Rezkonv_ aims to improve the Mealmaster format by lifting some of its character +limits, adding new syntax, and translating it to german. However, the +specification is available on request only. + +A second format some programs can import is MasterCook_’s MXP_ file +format and its XML-based successor, MX2. Beyond that there exist numerous +application-specific, proprietary formats: + +`Living Cookbook`_ + Uses a XML-based format called fdx version 1.1. There’s no specification to + be found, but a few + `examples <http://livingcookbook.com/Resource/DownloadableRecipes>`_ + are available, and those are dated 2006. +`My CookBook`_ + Uses the file extension .mcb. A specification `is available + <http://mycookbook-android.com/site/my-cookbook-xml-schema/>`_. +KRecipes_ + Uses its own export format. However, there is no documentation whatsoever. +Gourmet_ + The program’s export format suffers from the same problem. The only + document available is the `DTD + <https://github.com/thinkle/gourmet/blob/7715c6ef87ee8c106f0a021972cd70d61d83cadb/data/recipe.dtd>`_. +CookML_ + Last updated in 2006 (version 1.0.4) for the german-language shareware + program Kalorio has a custom and restrictive license that requires + attribution and forbids derivate works. +Paprika_ + Cross-platform application which supports its own “emailed recipe format” and a + simple YAML-based format. + +.. _Paprika: https://paprikaapp.com/help/android/#importrecipes + +.. _xml-formats: + +Between 2002 and 2005, a bunch of XML-based exchange formats were created. They +are not tied to specific software, so none of them seems to be actively used +nowadays: + +RecipeML_ + Formerly known as DESSERT and 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. +eatdrinkfeelgood_ + Version 1.1 was released in 2002 as well, but the site is not online + anymore. The DTD is licensed under the `CC by-sa`_ license. +REML_ + Released in 2005 (version 0.5), aims to improve support for commercial uses + (restaurant menus and cookbooks). The XSD’s license allows free use and + redistribution, but the reference implementation has no licensing + information. +`RecipeBook XML`_ + Released 2005 as well and shared under the terms of `CC by-sa`_ is not + available on the web anymore. + +.. _CC by-sa: https://creativecommons.org/licenses/by-sa/2.5/ + +.. _obscure-formats: + +Finally, a few non-XML or obscure exchange formats have been created in the past: +YumML_ is an approach similar to those listed above but based on YAML instead +of XML. The specification has been removed from the web and is available +through the Web Archive only. + +`Cordon Bleu`_ (1999) encodes recipes as programs for a cooking machine and +defines a Pascal-like language. Being so close to real programming languages, +Cordon Bleu is barely usable by anyone except programmers. Additionally, the +language is poorly-designed since its syntax is inconsistent, and the user is +limited to a set of predefined functions. + +Finally, there is RxOL_, created in 1985. It constructs a graph from recipes +written down with a few operators and postfix notation, and does not separate +ingredients and cooking instructions like every other syntax introduced before. +Although Pesto is not a direct descendant of RxOL both share many ideas. + +microformats.org_ has a similar list of recipe interchange formats. + +.. _REML: http://reml.sourceforge.net/ +.. _eatdrinkfeelgood: https://web.archive.org/web/20070109085643/http://eatdrinkfeelgood.org/1.1/ +.. _RecipeML: http://www.formatdata.com/recipeml/index.html +.. _CookML: http://www.kalorio.de/index.php?Mod=Ac&Cap=CE&SCa=../cml/CookML_EN +.. _Meal-Master: http://web.archive.org/web/20151029032924/http://episoft.home.comcast.net:80/~episoft/ +.. _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://web.archive.org/web/20150814041516/www.dodomagnifico.com/641/Recipes/CompCook.html +.. _Gourmet: http://thinkle.github.io/gourmet/ +.. _KRecipes: http://krecipes.sourceforge.net/ +.. _Cordon Bleu: http://web.archive.org/web/20090115210732/http://www.inf.unideb.hu/~bognar/ps_ek/cb_lang.ps +.. _microformats.org: http://microformats.org/wiki/recipe-formats +.. _Living Cookbook: http://livingcookbook.com/ +.. _My CookBook: http://mycookbook-android.com/ + +.. 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: + +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 unsuitable, and the interchange formats listed +`above <xml-formats_>`_ have largely failed to gain traction. Even though +simple, XML 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.” An excellent example +of this is Markdown_. + +.. _Markdown: https://daringfireball.net/projects/markdown/syntax + +We also must acknowledge that machines play an important role in our +daily lives. They can help us, the users, accomplish our goals if they +can also understand the recipes. 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 themselves. 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: + +Introduction by example +----------------------- + +.. code:: + + So let’s start by introducing Pesto by example. This text does not belong + to the recipe and is ignored by any software. The following line starts the + recipe: + + %pesto + + &pot + +1 l water + +salt + [boil] + + +100 g penne + &10 min + [cook] + + >1 serving pasta + (language: en) + +And that’s how you make pasta: Boil one liter of water in a pot with a little +bit of salt. Then add 100 g penne, cook them for ten minutes, and you get one +serving pasta. That’s all. + +There’s more syntax available to express alternatives (either penne or +tagliatelle), ranges (1–2 l water or approximately 1 liter water), and metadata. +But now you can have a first peek at `my recipe collection`_. + +.. _my recipe collection: https://codeberg.org/ldb/rezepte + +.. include:: Pesto/Parse.lhs +.. include:: Pesto/Graph.lhs +.. include:: Pesto/Lint.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:: ../../exe/Main.lhs +.. include:: ../../exe/Test.lhs +.. include:: ../../exe/Doc.lhs + |