summaryrefslogtreecommitdiff
path: root/src/Codec/Pesto.lhs
diff options
context:
space:
mode:
authorLars-Dominik Braun <lars@6xq.net>2020-08-24 17:09:34 +0200
committerLars-Dominik Braun <lars@6xq.net>2020-08-24 17:09:34 +0200
commit295dd897297722d07ec2ce5fb82e323fe495c775 (patch)
tree8d9de652a030c34c6be775ca31c159620f52fbf1 /src/Codec/Pesto.lhs
parent39f9263fa38c32ce2e3a4f4bedb8349da47a3200 (diff)
downloadpesto-295dd897297722d07ec2ce5fb82e323fe495c775.tar.gz
pesto-295dd897297722d07ec2ce5fb82e323fe495c775.tar.bz2
pesto-295dd897297722d07ec2ce5fb82e323fe495c775.zip
GHC 8.8, cabal 3, pandoc 2.10 compatibility
Move files around to separate Pesto (the library) and Pesto (the executables). Fixes for pandoc API changes.
Diffstat (limited to 'src/Codec/Pesto.lhs')
-rw-r--r--src/Codec/Pesto.lhs286
1 files changed, 0 insertions, 286 deletions
diff --git a/src/Codec/Pesto.lhs b/src/Codec/Pesto.lhs
deleted file mode 100644
index 098f9cb..0000000
--- a/src/Codec/Pesto.lhs
+++ /dev/null
@@ -1,286 +0,0 @@
-=========================
-Pesto specification draft
-=========================
-
-Pesto is a text-based human-editable and machine-transformable cooking recipe
-interchange format.
-
-.. warning::
-
- This specification is work-in-progress and thus neither stable, consistent or
- complete.
-
-.. 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.
-
-__ motivation_
-__ introduction-by-example_
-__ language-syntax_
-__ language-semantics_
-__ linting_
-
-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 <mailto:lars+pesto@6xq.net>`_
-
-.. _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 use it, 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 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 its own recipe file format. Some of
-them, due to their age, can be imported by other programs.
-
-Meal-Master_ is one of these widely supported formats. A huge 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, as
-well as its XML-based successor MX2. And then there’s a whole bunch of
-more-or-less 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__ 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 licence that requires
- attribution and forbids derivate works.
-Paprika_
- Cross-platform application, supports its own “emailed recipe format” and a
- simple YAML-based format.
-
-__ http://livingcookbook.com/Resource/DownloadableRecipes
-.. _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 a 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 permits free use and
- redistribution, but the reference implementation has no licensing
- information.
-`RecipeBook XML`_
- Released 2005 as well and shared unter the terms of `CC by-sa`_ is not
- available on the web any more.
-
-.. _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 useable 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. It 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://www.dodomagnifico.com/641/Recipes/CompCook.html
-.. _Gourmet: http://thinkle.github.io/gourmet/
-.. _KRecipes: http://krecipes.sourceforge.net/
-.. _Cordon Bleu: 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
------
-
-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: 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:
-
-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 own recipe collection`_.
-
-.. _my own recipe collection: https://github.com/PromyLOPh/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:: ../Main.lhs
-.. include:: ../Test.lhs
-.. include:: ../Doc.lhs
-