PREPARATION FOR MIGRATING RECIPES FROM ONE SYSTEM TO ANOTHER

ANATOMY OF A RECIPE

Recipes can be very simple, or incredibly complex. Some recipes have only text content, as when describing a process: "How to tenderize meat". This article is intended to serve two purposes:
1. Describe the elements of recipes, and how they should be written.
2. Describe how to prepare recipes for export from an existing system into a new system. (recipe/cookbook manager)

The process of moving recipes from one system to another is accomplished by first exporting the recipes from the original system, then importing them into the new system, or, in some cases, a translator is used to process the original export and the result of the translator is imported into the new system. Some systems have a number of export formats, and some can import multiple formats.

Regardless of how the process is performed, it is important that the recipe structure be correct, or else the translator that is used can and probably will make errors. If the original recipe has errors, the translator can make additional errors, because translators expect things to be in the correct fields and format for whatever format the original system requires.

Recipe elements are stored in 'fields' in each system. Different systems have different 'field lengths' for their fields, so when translating from one system to another, such limitations can present problems, causing data to be lost if a long field is translated into a short field, for example. Often, you will see recipes with a few words missing on the ends of lines - this is an example of such data loss. For example, if a description is present, it may be limited to just a few words in one system, while in another system, it can consist of several paragraphs. Often, such 'truncations' will be seen in ingredient lines, because of the generally shorter fields in ingredient lines. Sometimes, these data losses render a recipe unusable.

Each system is different. A system can have fields for many things, or they may only have a few fields, and the content can be relatively free form. When translating from a free form system into a more complex system, it is important that the various recipe elements be recognizable by the translator by using names that are recognizable. Recipe elements are described below.

RECIPE ELEMENTS:
TITLE: Every recipe requires a title. All recipe managers use the title to arrange the recipes among each other. Some recipes have a second title, as when including a foreign recipe name with an English recipe name. If a second title is present, it should be on the same line as the main title, and inside parentheses.

DESCRIPTION: Optional. Some recipes have a section that describes the recipe, the region it came from, or other information about the recipe in general. In all cases, if the description is removed, the recipe should not be affected at all.

NOTES: Optional. Some recipes have a few sentences or paragraphs about the recipe. Often, the description will be stored in the notes section, perhaps along with other paragraphs about the recipe itself.

INGREDIENTS: Most recipes have ingredients, but some recipes are text only as referenced above. At the end of this document, a rather lengthy discussion of how recipes lines should appear is presented. When a recipe has no ingredients, the words 'See directions' should appear on the first ingredient line. (Some systems will balk if there are no ingredients at all.)

DIRECTIONS: Most recipes have directions to describe how to modify the ingredients to create the recipe. Directions are not absolutely necessary, but few recipes consist of only ingredients. The paragraphs in recipes that are all text with no ingredients will generally be treated as directions.

Many recipes will consist of only a title, a list of ingredients, and directions to prepare the recipe. However, there are many more recipe elements that may be present.

YIELD: The yield of a recipe describes how much the total recipe makes. The yield should not describe how many servings are created by the recipe, but rather the yield of the entire recipe. So a yield may be 24 cookies, for example, but it may serve 12 people at two cookies per serving. A yield should consist of a number, and a 'unit' or name of the food being prepared, as in 24 cookies or 2 cups.

SERVINGS: Servings describes how many people can be served from the recipe. Servings is a whole number only. A recipe cannot serve 3 1/2 people. While it is sometimes possible to write a servings with a fraction, most translators and recipe managers will make an error if a fraction is present.

SERVING SIZE: Serving size explains how the yield is divided up to create servings. In the cookie example above, the serving size is 2 cookies, the yield is 24 cookies, and the servings is 12.

Recipe managers differ in which yield fields are supported, and how they are managed. Some recipe managers use these fields to determine how to resize a recipe from, say 4 servings to 6 servings.

TIME: Times tell the user how much time to provide for various steps. There are over 30 different times, such as preparation time, cooking time, marinating time, etc. Each system has a different way of storing times, so translation can be error prone. If there are multiple times involved, each should be on its own line, or in its own field. Some times are described as 'alternate times' in recipe managers.

SOURCE: The source is usually defined as the publication or other source, as oppposed to an author. A source could also be a URL, if the recipe is found on the internet.

AUTHOR: The author is generally defined as the author of a book that is the source, or the person that created the recipe.

CATEGORIES:
Categories are used to sort, or filter recipes based on a given word or words. For example, a chicken recipe might have a category of chicken, or poultry. Other categories might be barbecue, picnic, etc. Generally recipe managers can find recipes if the word wanted appears in the ingredients, but a term like 'Thanksgiving' probably only occurs in a category. Categories should be separated by semicolons.

CUISINE:
A cuisine tells what country or region a recipe is from. Most recipe managers support only one, if any.

SERVING IDEAS: Serving ideas are generally sentences or paragraphs that suggest ways to serve the recipe, which may also include the names of other recipes. Or, for a soup recipe, it may say 'Serve with crusty bread.'.

NUTRITION: Some recipe managers use the ingredient list to determine the major nutrient elements, such as calories, fat, and so on. In order for nutrition to properly determined, the ingredient list must be fairly precise. For example, if the recipe lists 1 bag shredded carrots, the system may not know how much carrot is used. Even if you list it as follows: 1 (10-ounce) bag shredded carrots, the system may not be able to establish that 10 ounces of shredded carrot is required. The problem here is that bags, packages, cans, etc, are not fathomable by most recipe managers. The correct way to write an ingredient line if nutrition is important is as follows: 10 ounces shredded carrot. Recipes should use weights and measures that are standard, rather than cans, cartons, packages, etc.

OTHER FIELDS:
Some other fields might be Keywords, Tips, Equipment, Oven (temperature), Variations, etc. Each system will support some fields, and may not support others. The key thing is to make sure that each field starts with one of these keywords so the other system can attempt to recognize it.

URLS: Some recipe managers support URL's, others don't. URL's should be complete, including the http:// and the www, if present, plus the final .com or whatever is required to actually visit the URL. For example, do not write "amazon.com" as a URL, because even though you can see what it is, and Google can find it, few recipe managers will recognize it as a URL.

MULTIMEDIA:
Most recipe managers support at least one photo for the recipe. Some support more photos, audio files, movie files and the like. In many cases, none of these will export and import into a new system, so it may be necessary to handle that part manually. Many of the exports are text only, which excludes photos. In those cases, it may be necesary to copy the photo from the original and paste it into the new system.

PREPARING TO EXPORT FROM AN EXISTING SYSTEM: 
The best way to minimize errors when exporting from one system and importing into a new system is to make certain corrections to the existing recipes so that the transfer will be less problematic. The following ideas will help. Sometimes it is important to learn the limitations of the new system. Otherwise, data may be lost when importing into the new system, if it doesn't have as much 'room' in a field for a recipe element. For any recipe element that does not exist in the new system, copy or move the data in the original system into the directions section and provide a keyword so it can be recognized. 

Titles: Most recipe managers permit only one recipe with a given name. If you have multiple recipes with the same name, but they are different recipes, you should rename one or both of them to set them apart. Often, it is simply a matter of adding a '2' to one of them.

Recipe titles should not use accented characters, nor any of the following characters:
\ / : * ? " < > | These are limitations in the Windows operating system, so do not use these characters in recipe titles, because often, when exporting photos, the photo name will be taken from the recipe title. If these characters are in the recipe title, it will have to be modified during the export because the photo requires a file name. The newer system may lose track of the photo if its name is different from the recipe. There should be nothing in a recipe title except the title itself, with an alternate title in parentheses, if present. Do not use a slash character between the actual title and the alternate. Accented characters may be 'coded' in an export, and the importing system may not understand the coding. For example an ampersand may be encoded as '&amp;' in a title. The new system may not recognize that as '&', and worse, it may name an accompanying photo with the coded value, leading to further problems. There are many accented characters that may not be recognized in the new system if they are encoded as above.

Notes, Directions, Tips, Serving Ideas and any other elements that consists of sentences:
These should be full sentences, starting with a capital letter (for the first word) and ending with line punctuation such as period, exclamation point or question mark (in addition to any parentheses or quotes.) In other words, full sentences. If there are multiple sentences in a paragraph, each should start and end correctly. If there is a 'header', or subtitle, end it with a colon, which will help keep the header and the following text together.

Servings, yields, etc:
These should be marked as they should be for the new system. In cases where they are not explicitly supported in one or the other systems, the word 'Makes, Serves, or Yield' should begin the line, using a capital letter. Periods are not required for these lines.

Times, and other elements that are coded in some way:
Most of the time, the existing system and the newer system can exchange coded elements, as long as both systems support the field. If the newer system does not support a given field, it may be necessary to write out the field in text in the original system, in the directions section so that it is not lost.

In general, if the newer system is able to calculate nutrition, it will expect a single amount, a single unit, a single properly described ingredient, and it won't care about the preparation. If alternates (signified by the word 'or', are present, they should follow the amount/unit/ingredient/preparation terms. This is by far the largest area of errors, because no system can make sense out of alternatives. At best, it will be ignored, at worst, it will be mistaken for the primary ingredient.

INGREDIENTS:
Ingredients are, by far, the most problematic elements to exchange between systems. This is because most recipes are not written with computers in mind, and are thus subject to many errors during exchange. Errors may compound during an exchange if the original has errors. It is usually harder to fix the resulting errors than to make corrections in the original. Additionally, by making corrections in the original, there will be a good backup if needed.

Ingredient fields are composed of 4 major parts, and up to 30 minor parts. The major parts are Amount or Quantity, Units, Ingredient name and preparation. Some systems do not contain a preparation field, so that text is kept in the ingredient field. These systems generally do not support nutrition calculation, as additional text in an ingredient field will generally throw off the calculation or mislead the nutrition calculator about the actual ingredient used. The minor parts may be phrases such as 'divided', 'optional', 'with heads and tails', etc. In other words, descriptive information about the ingredient that is not part of the ingredient's name.

Sentences should NEVER be included in ingredient lines. If a sentence is needed, it should become a note and an asterisk or (see note) should be in the ingredient line. (Most common sentence in ingredient lines: I used xyz.)

Amount/Quantity:
Most systems permit only a single amount, using numbers only, but including fractions and decimal points. If the original system uses a 'range', such as 2-3 eggs, then the range should be placed in parentheses, at the end of the line, and the smaller number used as the quantity. Remember, nutrition cannot be calculated on a range. Do not spell out numbers in this field. 

Unit:
The unit is how the ingredient is measured. It could be in the traditional teaspoons, tablespoon, and cups, or it could be subdivisions of the food itself, such as 3 sections orange.

Most systems support only one unit. Often recipes are written using both US and metric units. When multiple units are present, the second one should be placed at the end of the line. Sometimes, a unit will have an adjective, such as 1 (rounded) teaspoon salt, or 1 (10-ounce) can peas. The rule is to place these adjectives into parentheses, after the amount, and before the actual unit. If the paren phrase is removed, it should not affect the recipe, or at least the calculation of nutrition. (As mentioned above, if cans or other packages are used, it may throw off nutrition calculation because the calculators generally expect weights or standard volumes such as cups.) A good way to test for units is to mentally add the word 'of' to the line. While the word should never be included in an ingredient line, 3 cups OF sugar, is understandable, but 3 large OF apples does not make sense. Large, in this case, is not a unit, it is part of the ingredient field.

Units should always be spelled out completely to prevent errors. For example there are over 30 ways to abbreviate tablespoon, counting variations of spelling, capitalization and use of periods. If abbreviations must be used to prevent truncation, periods should not be included. The only period that should ever appear in an ingredient line is a decimal point in a number.

Ingredient:
The ingredient field describes what is measured by the amount and unit. This is an area of huge errors, because in order for nutrition to be calculated, the system must know what is measured. Example: 1 cup carrots, shredded. This is a common mistake, because what is in the cup is shredded carrot, not whole carrots. The USDA nutrition calculator requires knowing what is being measured in order to provide a nutrition count. The easiest way for a person to consider the proper phrasing of the ingredient vs the preparation is to remember the term 'mise en place', which means everything in its place. Think of tv cooking shows that have each ingredient premeasured and in its measurement device. The ingredient field should describe what is measured. As we will see shortly, preparation is what is done to an ingredient AFTER it is measured out. In most cases, the descriptive terms should precede the ingredient name, and commas should not be used. Commas are intended to set out different thoughts, or different activities, but they do not belong in adjectives. Some systems will automatically use the first comma to identify the separation between the ingredient and preparation. So, a term like 3 skinless, boneless chicken breasts may end up in the system with 'skinless' as the ingredient and boneless chicken breasts as the preparation simply because of that comma. Of course, nutrition cannot be calculate on '3 skinless', so that would fail.

Preparation:
The preparation field is intended to describe any activity that takes place upon the measured ingredient after it is measured. For example, it may be ,3 cloves garlic, smashed with the flat side of a knife'. This tells you to measure out 3 cloves of garlic, and then, at some point after gathering them, to smash them flat.

With 30+ alternative minor ingredient descriptors, it is necessary to fit them into the traditional 4 supported fields. If nutrition is important to you, where these alternative elements is stored makes a difference in the system's ability to recognize the nutrition of the ingredient. So, it is often best to store these alternative terms in the preparation field, which is not involved in determining nutrition. For example, '3 large eggs, at room temperature' is easily recognized by most systems because the 3 large eggs is used to calculate nutrition. However, if it were written thusly '3 room-temperature large eggs', then most systems would make an error in calculating the nutrition, because there is no definition for nutrition of an egg that is defined as being a specific temperature. This is a valid way to write the ingredient line for a print or online recipe, but it does not work in a computer if nutrition is to be calculated.

When alternative terms are used, it is often best to enclose them in parens, in the preparation field. This permits them to be contained as a single thought so that the newer system doesn't make an error in the translation. In the above egg example, it might be written as 3 large eggs, (at room temperature). While this is no more correct than the version without the parens, there could be several other phrases present in the preparation field as well. Example: 3 large organic eggs, such as Eggland Best, at room temperature. Both phrases could be placed into parenthesis without changing the ability to prepare the recipe.

Other things to watch for in ingredient lines:
Most systems are designed to contain one ingredient per ingredient line. But often, you will see a line such as 1 teaspoon each: salt, pepper, cayenne, sugar. No system can 'understand' such a line. That needs to be on 4 lines. 

Plus:
Often the word 'plus' will appear in an ingredient line, sometimes more than once. In some cases, it is intended to identify a second ingredient, or a second amount and unit of an ingredient. To minimizer errors, the plus should be replaced by placing the second ingredient on its own line. For example, 1 cup plus 2 tablespoons sugar cannot be understood by a computerized recipe manager. That should be 1 cup sugar, (possibly with 'plus' at the end of the line in the preparation field) with 2 tablespoons sugar on the second line.

In other cases, plus is used to describe a completely different ingredient, such as 1 cup water plus 1 teabag Oolong tea. While this is a simplistic representation, lines can be very much more complicated. In this case, the word 'plus' is simply not needed and each ingredient should have its own line.

Or:
The word 'or' is often found in ingredient lines. Most often, it is not used correctly for computerized recipe managers. While the human can easily understand '1 teaspoon coarse or fine salt,', a computer will see 'coarse or fine salt' as an ingredient, and will not be able to calculate nutrition (sodium in this case) as a result. This rule will always provide the best result:
List the amount, unit, ingredient first, and THEN the alternatives. For example: 1 teaspoon coarse salt, (or fine salt). Now, the computerized system will see 'coarse salt' which it will recognize.

Capitalization:
When no amount or unit is present, such as 'Pepper, to taste', the ingredient should be capitalized. In no other case should it be capitalized, unless it is a trademarked name (Pickapeppa), or a word in a recipe name, which should follow normal title casing rules. Ingredient lines (and any other part of a recipe) should never be written in upper case. they should always be in lower case except as listed above.

Subtitles:
An ingredient subtitle is a word or phrase that describes what follows. For example a pie recipe may have a subtitle for crust and another for filling. These subtitles are not ingredients themselves, and should be marked to distinguish them by adding a colon to them. It is best to capitalize all the letters in a subtitle, but not necessary if the colon is present. When subtitles are used, it should be clear where the ingredients for that subtitle end, and other ingredients begin. (This is for the understanding of the user of the recipe, but the recipe manager should not care.)

GENERAL CONCEPTS:
Multiple recipes in one recipe:
Often, as in the section of subtitles shows, two recipes can be written together into a single recipe by using subtitles to separate them. In other cases, a whole separate recipe might exist in a recipe, with two ingredient sections and two directions sections. There are two ways to handle this:
1. Separate out the second recipe as its own recipe, especially if used by other recipes. For example, you might have a recipe for Peach Pie Filling as a separate recipe, and then list that as an ingredient in multiple other recipes.
2. Merge the two recipe together using subtitles between the ingredient sets, and between the directions steps. This is likely to provide the best nutritional results, as not all systems will be able to calculate the nutrition of a separate recipe used in a first recipe. By merging them, all the ingredients are seen by the nutrition calculator.

Capitalization:
Recipes should always be in lower case, with specific words capitalized as described above. Recipes in all upper case can often not be transferred at all, or are transferred with errors.

The new system:
It is worth learning about the new system before trying to import from another system. Take especial note of field sizes of both systems so you can identify potential data loss locations.

Learn what units the new system supports, and compare that to the units in the existing system. It may be necessary to make some corrections in the original.

Abbreviations:
In general, it is best to use no abbreviations in recipes. Often, when abbreviations are used, a period can be mistaken for the end of a sentence, instead of recognizing that it is simply denoting an abbreviation. If terms are used that are generally shown as abbreviations, such as U.S.A., the periods should be eliminated as USA, with a period after the 'A' only if it is the end of a sentence.

Symbols:
Symbols that are substituted for actual words, particularly units, should never be used. MOST systems will not understand the double quote ["] as equivalent to the term 'inch' for example. Always write out the word 'inch', including a hyphen if needed. The pound sign [#] should not be used to replace the word 'pound'. It can be used in other contexts, such as '#2 can', but it is better to leave that out entirely, and substitute the weight instead. Example:
A #2 can holds 1 pound 4 ounces, or 2 ½ cups
This leads to another possible error source, the mixing of pounds and ounces. Most systems do not support that, because it is two amounts and two units on one ingredient line. This can be corrected by converting to all ounces, or pounds with a decimal. Above, that would be 1.25 pounds, or 20 ounces. But 2 1/2 cups would work just as well. Remember, weights are always best, and cans and other arbitrary packages are likely to not have nutrition calculated properly because there is no 'standard' for such packages, and even if you can fit the size into the ingredient line, it may be ignored. In general, never use a symbol where it is a replacement for a word.

Ingredient lines: Make certain there is no punctuation on the end of an ingredient line - it may cause the new system to cause an error. As previously mentioned, do not write sentences into ingredient lines. Make sure ingredient lines have only one amount, one unit and one ingredient in an ingredient line. (Except if following 'or' or 'plus'.) Make sure that any ingredient line that appears split across more than one line in the original system is corrected before exporting. 

Spelling:
It is best to run a spell checker, if present, on the original source. Many words appear in recipes misspelled, because many recipes are typed in manually, and a misspelling is often overlooked. But if a misspelling is in a critical location as in a unit, ingredient or field name, it can lead to troublesome errors when imported into a new system. It is also a good thing to run a spell checker in the new system, right away, to see if there is a compatibility problem between the original and new system.

General precautions:
Each item in a recipe should be recognizable by a computer. That is generally done by using a keyword before the item. If you export a recipe and look at the export text, you will see the tags on the items. If something exists that has no tag, it may not be properly understood by the importing system. One example is a person's name on a line by itself. No system will treat that correctly, as it is not a sentence, and it has no tag. If it is preceded by 'Author:', however, it will be ok. However, if not tagged, it can lead to being placed in the wrong place in the new system, perhaps even the ingredient section. Or, it may be lost. Or, it may be stuck onto the end of whatever preceded it. Make sure punctuation is present where expected. Do not end lines with commas or semicolons unless they are meant to be joined back together. Here is another example of a real export:
This is from The Barbecue Bible
The above is not a sentence, nor is it tagged. Therefore, the new system may not know where it goes. However, this would be fine:
Source:This is from The Barbecue Bible
Now, it has a tag, and even though there are extra words, the importing system will recognize it as a source, if it is supported.

Summary:
Moving recipes from one system to another can be a tedious task. It is kind of like moving from one house to another - it is a fairly permanent migration, and must be done correctly in order to enjoy the results. If a recipe is worth migrating to a new system, it is probably worthwhile making it correct in the old system so that it appears correctly in the new system.