Copy-edit specification

1 files changed, 78 insertions, 85 deletions

diff --git a/src/lib/Codec/Pesto.lhs b/src/lib/Codec/Pesto.lhs
index 7a2b615..ba8e332 100644
--- a/src/lib/Codec/Pesto.lhs
+++ b/src/lib/Codec/Pesto.lhs
@@ -1,15 +1,10 @@
-=========================
-Pesto specification draft
-=========================
+============================
+Pesto language specification
+============================
 
-Pesto is a text-based human-editable and machine-transformable cooking recipe
+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
@@ -19,8 +14,8 @@ 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
+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.
 
@@ -31,10 +26,10 @@ __ #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
+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
+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.
 
@@ -52,8 +47,6 @@ interpreted as described in `RFC 2119`_.
 :License: CC0_
 :Website: https://6xq.net/pesto/
 :Source code: https://codeberg.org/ldb/pesto
-:Contributors:
-	- `Lars-Dominik Braun <mailto:lars+pesto@6xq.net>`_
 
 .. _CC0: https://creativecommons.org/publicdomain/zero/1.0/
 
@@ -62,13 +55,12 @@ interpreted as described in `RFC 2119`_.
 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
+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). Additionally parsing HTML pulled from the web is a
-nightmare and thus not a real option for sharing recipes. h-recipe_ provides a
+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
@@ -77,13 +69,12 @@ second vocabulary that has not been adopted widely yet.
 
 .. _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>`_
+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/
@@ -109,41 +100,41 @@ exist. A Meal-Master recipe template might look like this:
     -----
 
 Rezkonv_ aims to improve the Mealmaster format by lifting some of its character
-limits, adding new syntax and translating it to german. However the
+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:
+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.
+	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.
+	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
+	program Kalorio has a custom and restrictive license that requires
 	attribution and forbids derivate works.
 Paprika_
-	Cross-platform application, supports its own “emailed recipe format” and a
+	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 a specific software, so none of them seems to be actively used
+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_
@@ -155,30 +146,30 @@ eatdrinkfeelgood_
 	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
+	(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 unter the terms of `CC by-sa`_ is not
-	available on the web any more.
+	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
+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
+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. It does not separate
+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.
 
@@ -211,31 +202,33 @@ microformats.org_ has a similar list of recipe interchange formats.
 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_.
+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 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.
+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 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.
+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:
 
@@ -244,33 +237,33 @@ 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:
+    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
+    %pesto
 
-	&pot
-	+1 l water
-	+salt
-	[boil]
+    &pot
+    +1 l water
+    +salt
+    [boil]
 
-	+100 g penne
-	&10 min
-	[cook]
+    +100 g penne
+    &10 min
+    [cook]
 
-	>1 serving pasta
-	(language: en)
+    >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
+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`_.
+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 own recipe collection: https://codeberg.org/ldb/rezepte
+.. _my recipe collection: https://codeberg.org/ldb/rezepte
 
 .. include:: Pesto/Parse.lhs
 .. include:: Pesto/Graph.lhs
@@ -280,7 +273,7 @@ But now you can have a first peek at `my own recipe collection`_.
 Using this project
 ------------------
 
-This project uses cabal. It provides the Codec.Pesto library that implements
+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.