Grocery Consumer Terminology
	
Shopping List
The primary output of the Grocery Consumer (hereinafter called GC) is a shopping list and its
cost at various stores, generated from a menu that you create and price lists that you maintain.
The shopping list is a complete list of ingredients, units, and quantities needed for all recipes
selected for meals in the menu period.  The shopping list is overwritten automatically each time
you change or create the menu.  GC keeps the shopping list from the latest menu in the file
"latest.shp".  User can edit the shopping list using the Shopping List... option under the Edit
menu to 1) delete items user has in stock; and 2) add miscellaneous ingredients that are not part
of any recipe (e.g., cat food, toilet tissue, etc.).  Miscellaneous items are merged alphabetically
into the shopping list.  Maximum total number of items on shopping list is 1000.

Menu
A menu is a list of recipe names that the user has selected for breakfast, lunch, and dinner for a
single or multi-day menu period.  Each time a menu is created, the shopping list is automatically
created from the ingredients and quantities used by the recipes in the menu.  The GC user can
edit the latest menu at any time (add, drop recipes for any meal) by selecting the Menu... item
under the Edit pulldown menu.  Each day of the menu period is presented in succession to the
user; the user can keep or change each day's menu selections.  Maximum number of days in a
menu period is 28 (4 weeks).  GC keeps the latest menu selections in the file "latest.mnu".  This
file is overwritten each time the menu is changed or recreated.

Recipes (dishes)
A recipe for a dish includes the recipe name, the recipe contributor name, the contributor's city,
the recipe ingredients, a unit of measure for each ingredient, a quantity (# units) for each
ingredient, a preparation for each ingredient if desired, and recipe directions.  These items are
optional except for the recipe name, ingredients, units, and quantities.  Recipe elements are
described here:

	ingredients = food items to be used in recipe
		examples: 	tomato sauce
				milk

	unit of measure = how amounts of each ingredient are to be measured
		examples: 	cup
				teaspoon
				quart
				package (8 oz)
				can (21 oz)
				gallon
				oz
				(use the word "each" if measured as a single item)

	quantity = number of units required for each ingredient (numerical quantity as decimal or
									fraction)
		examples:	1
				12 	(do not use character strings like  "dozen")
				1/4	(handled internally as 0.25)
				0.25
				1/2	(handled internally as 0.5)
				1-1/2	(handled internally as 1.5)
				1 1/2	(handled internally as 1.5)
				1 -1/2	(handled internally as 1.5)
				1- 1/2	(handled internally as 1.5)
				1.5 	
				1.67
				8/3	(handled internally as 2.667)
	
	preparation = how ingredient is to be prepared
		examples:	diced
				sliced
				ground
				crushed

	directions = text on how ingredients are to be mixed and cooked
		example:   Mix all ingredients in bowl.  Cook for 30 minutes.  Eat.

The user can add and remove recipes from the recipe database.  The user can modify any
recipes in the database simply by selecting Recipes... from the Edit menu, selecting a recipe and
then editing any of the components of the recipe.  Recipe name, contributor name, contributor
city, ingredients, units, preparation, and directions are all character strings.  Like all Windows
software, use the Tab key or a mouse click to move the cursor from one text box to the next for
data entry.  Numerical quantities should be used (like 1.5), so user should not use a character
string like "dozen" for a quantity.  Fractions are allowed (see the description of Quantities that
follows). The recipe database is a random access file named "recipes.gc2".  Do not rename this
file or alter it in any way, or your recipes will be corrupted.

Some recipes you may wish to enter are actually courses which include several dishes.  Recipes
in this database are limited to 15 ingredients and directions are limited to 600 characters.  GC is
thus designed for recipes of "dishes" rather than of "courses".  If your recipe includes multiple
dishes, it is usually best to break it into separate recipes.  Use a similar name for the two recipes
to force them to appear together in alphabetized lists.  For example, Roast Chicken and Dressing
can be broken into two recipes and listed as "Roast Chicken" for the main recipe and "Roast
Chicken:  Dressing" for the dressing portion of the recipe.  In this manner you could have 30
ingredients and 1200 characters for the directions between the two recipes.  Simply refer to the
dressing recipe in the directions for the main recipe.  For example, one line in the directions
could read "Prepare dressing according to the recipe for Roast Chicken:
Dressing".

Droplists are provided for ingredients, units, and preparations for convenient selection when the
user is entering recipes into the database.  Droplists illustrate typical words and phrases for user
entries and greatly minimize keystrokes for input.  It is best to be consistent in your terminology
and capitalization (use all lower case except for brand names); this way your shopping list will
add quantities of identical items.  If you are not careful about this, the shopping list will show like
like items as different items simply because of small discrepancies in terminology or
capitalization.

Ingredients (Recipes)
Ingredients are items that are used in recipes (dishes), such as flour, baking soda, butter,
pepper, and milk.  Ingredients, along with directions, are the primary building blocks of recipes.
Ingredients can be added or removed from recipes in the database.  A separate droplist of
ingredients from which the user can select ingredients for recipes is maintained as "ingred.lst".
The user can add or remove ingredients to this list or refresh (update) the list using ingredients
from all recipes in the user's recipe database.

Units of Measure (Recipes)
Units are how the ingredients are measured.  For example, "can (32 oz)" is a unit of measure for
tomato sauce; "teaspoon" is a unit of measure for pepper.  Units of measure are entered for each
ingredient used in a recipe.

Make sure you enter a unit for every ingredient in a recipe (actually, GC requires this).  If an item
is an individual that is not commonly measured in any other quantity (e.g., egg), use "each" as
the unit.  However, almost any item has some other measure like lb or dozen that should be
used instead of "each" where possible.

Ingredients with identical name and unit combinations will have their quantities summed for the
shopping list.  Thus, an ingredient called for by several recipes in the menu period using the
same unit of measure will appear only once as an item on the shopping list, with the quantities
summed.  If a different unit of measure is used for the same ingredient by different recipes,
these will appear as separate entries in the shopping list.

No attempt is made in GC to add unlike units, like teaspoons and gallons, although this feature
may appear in future versions (if enough users request it).  It could be easily done now that a
units conversion routine has been included in GC.

A separate droplist of typical units of measure that the user can select for recipes is maintained
as "units.lst".  The user can add or remove units from this list or refresh (update) the list using
units from all recipes in the recipe database.

Quantities (Recipes)
A quantity is a numerical entity that defines the number of units of each ingredient required for a
recipe.  For example, "1/2" teaspoon is a quantity of pepper", and "2" cans (32 oz) is a quantity
of tomato sauce.  If your unit of measure for tomato sauce is oz, then your quantity might be
"64".  Obviously, "64" oz of tomato sauce is the same as "2" cans (32 oz) of tomato sauce.  The
preferred method is "2" cans (32 oz) because this is more descriptive than 64 oz and will be
more likely to have a price listed in your price list.  Thus, it will have a better chance of being
priced in your cost of shopping list calculation.  Cases like this where different unit and quantity
combinations are equivalent will work with Grocery Consumer, but they cannot be added so they
will both appear individually on the shopping list for that menu period without being summed.
Thus you may have "x" oz of tomato sauce as one item and "y" 32-oz cans of tomato sauce as a
separate item on the same shopping list.

The user is free to enter quantities as fractions if desired. The way the user inputs a quantity is
how the recipe will appear to the user on the Edit Recipe screen.  Examples of valid fractions are
1/4, 1/2, 5/3, 1 1/3, 1-3/4, 1- 3/4, etc., and compound fractions such as 1 1/8,1 1/3, 1-3/4, 1- 3/4,
2-9/16, etc.  Examples of invalid quantities are dozen, half, 1\2, 1+1/2, or any string exceeding 6
characters.

When preparing a shopping list, GC internally converts fractions to decimals so it can add like
items, so decimal equivalents appear in your shopping list instead of fractions.  Your recipes
remain unchanged; they appear as you input them (with fractions or decimals).

Preparations (Recipes)
A preparation describes how an ingredient should be prepared prior to use in a recipe.  For
example, "sliced" or "chopped" are two possible preparations for the recipe ingredient, onion.
Typical preparations from the droplist provided in GC can be used to create recipes.

The droplist of typical preparations that the user can select for recipes is maintained as "prep.lst".
The user can add or remove preparations from this list or refresh (update) the list using
preparations from all recipes in the recipe database.

Directions (Recipes)
Directions are written recipe instructions that the user must follow in preparing (e.g. blending,
cooking) the ingredients.  Directions, along with ingredients, are the building blocks of recipes.
Directions can be entered or edited in the directions panel of the Edit Recipes screen. This
screen is obtained by selecting Recipes... from the Edit pulldown menu, selecting a recipe, and
selecting Add/Modify (or simply double-click the recipe name you wish to edit).  Directions can
be up to 600 characters in length.

Miscellaneous Items
These are those items that you buy at the grocery store but which are not part of any recipe.
Examples are cat food, toothpaste, mouthwash, shaving cream, cookies, chips, etc.  A droplist of
miscellaneous items is provided when you edit the Shopping List so you can easily add these
items to your shopping list before printing it out.  You can edit the droplist of miscellaneous items
also.  Miscellaneous items are maintained in the file "miscitems.lst".


Grocery Consumer Activities

Getting Help
Almost every screen used by GC has a Help menu selection that gives context-sensitive help to
assist you with that screen.  These help items are very brief, documenting only those features
that may not be immediately obvious to the new user.  They are very enlightening, but they are
not intended to replace reading this manual.  You should read all help menu items and this
manual before contacting The Fox's Lair BBS for technical support.

Creating and Modifying Recipes in Your Recipe Database
Your GC software came with a recipe database of 16 recipes.  You can keep these original 16
and add to them or simply delete them to completely personalize your recipe database.  You can
create new recipes or change existing ones by selecting Recipes... on the Edit pulldown menu.
When shown the list of recipes in your database, you can remove recipes at this time.  If you
Delete recipes, you only remove them from the list on the screen.  You must Save Changes to
physically make the deletions in the recipe database.  You cannot Add/Modify a recipe if you
have deleted any recipes until you Save Changes.  If you want to add a recipe after removing
one, Save Changes, then select Add/Modify.

To edit a recipe, select (single-click) one from the list and press Add/Modify (or simply double-
click one).  To add a new recipe, type a new name in the text box and press Add/Modify (or
simply press Add/Modify and enter the name on the next screen).  This will bring up the recipe if
it exists, or it will bring up an empty form if it is a new recipe name.  You can then enter the
contributor name and city.  Then enter ingredients, units, quantities, and preparations for each
ingredient in the recipe, using droplists to prompt you for ingredients, units, etc and to minimize
keystrokes.  Use the Tab key to move the cursor from one text box to the next to avoid removing
your hands from the keyboard during recipe entry.  You can add or remove ingredients as you
wish, or edit an individual cell in the table with a click of the mouse and entering the replacement
text, using the backspace key to erase mistakes if necessary.  Enter the directions for the recipe
and you are done.  Press Save Changes to write the altered recipe into your recipe database.  It
is wise to Save Changes every now and then, even in the middle of recipe input.

Click the Next button on this screen to Save Changes and start a new recipe input.  Cancel puts
you back into the recipe selection screen.

Importing and Exporting Recipe Files
You can exchange recipes with whomever you want by importing and exporting recipe files.  All
or a subset of your recipe database can be exported by selecting "Export Recipes..."  in the File
pulldown menu.  This process creates a recipe file that has an ".rcp" extension.   At the end of
the process you will be prompted as to whether you want to ZIP (compress) the export file for
BBS transfer.  This step is recommended if you will be upload the recipe file to a BBS because
compressed files are smaller and file transfers are quicker.

You can import recipe files that you obtain from other users or the Fox's Lair BBS into your
recipe database using the "Import Recipes..." option under the File menu.  You will be prompted
to select the recipe file to import from a list of recipe files in your directory (*.rcp) or elsewhere on
your hard drive.  GC will add the .rcp extension for you if you do not include it.  GC will merge
the new recipes into your recipe database except for those with names that match any already in
your database.  If duplicate recipe names are detected, and you really want the imported recipe
with the duplicate name, you may want to rename the matching recipe in your database to
something else and then try the import again.

Creating and Modifying the Latest Menu and Shopping List
The Menu and Shopping List go hand in hand.  When you select Menu... from the Edit pulldown
menu, you will be prompted to select a menu period that contains from 1 to 28 days.
The default period, if you do not select one, begins and ends with the current date.  If you are
wanting to create a new menu with period different from the dates shown to you, change the start
and end dates by pressing the up or down spin buttons at the side of each date box.  If you are
wanting to edit the latest menu, you press the Start With Latest Menu button and the menu
period from the latest menu will be loaded.

Once you have set the menu period, press Proceed to move on to the daily menu selection.
Here, for each day of the menu period, you select (single-click) recipes from your recipe
database for the breakfast, lunch, and dinner meals on each menu day.  If you want to double a
recipe for a meal (company coming?), simply select it twice for a given meal.  Press Save when
the daily menu is done and you will move on to the next day.  You repeat this process for each
menu day in the menu period until the menu has been entered for the last day.  When you press
Save on the last day of the menu period, the menu file is overwritten and a new shopping list is
created.  Cost of the shopping list will be computed, if so desired, at this time.

The latest menu created and the shopping list that goes with it are both stored in files on your
hard drive ("latest.mnu", "latest.shp").  These files are overwritten each time you create or edit a
menu. You can individually edit the shopping list (Shopping List... under Edit pulldown menu) to
add miscellaneous items or remove items that you already have and do not need to buy at the
store.

Viewing the Latest Menu and Shopping List
You can quickly review the latest menu and shopping list using the View pulldown menu.
View provides a more compressed look at these items than Edit or Print.  You have no options
here for making any changes.

Viewing the Prices and Aisles List
Just do it.  All the prices and aisles for the store you are using are shown for all items that you
have entered into the price and aisle list.

Editing Prices and Aisles List
The price list is used to compute a cost of your shopping list at various stores.  The best way to
get prices into the list is to use your receipts from large grocery shopping trips to each of the
stores you frequent.  To get a price comparison across stores that is meaningful, GC must have
access to consistent price data.  This means that if you enter a price for an item at one store, you
are strongly encouraged to enter a price at all the other stores in your price list.  Otherwise, some
items will be included in the total shopping list price for some stores and not for others, making
the price comparison less useful.  You can, however, project the total cost of the recipe based on
the % of the shopping list and the cost computed.

The aisle list is used to build a shopping list by aisle for any of the stores you have on file.

The prices and aisles are physically located in the same file ("price.lst"), but they are edited as
separate lists for convenience.

Obtaining the Cost of a Shopping List
The shopping list cost is optionally computed immediately after the shopping list is created.  The
cost can be determined in Edit...Menu..., or after editing and saving the Shopping List, or just
before Viewing the cost of shopping list. The cost of a new shopping list can be viewed at any
time using the View...Cost of Shopping List menu item.

If there is no price for a shopping list item and unit combination in your pricelist, the item will not
be included in your cost for the shopping list, unless an appropriate units conversion is available.
For example, you have a recipe that calls for 3 oz of salt, but you do not have a per oz price for
salt in your price list.  You do have a price for a lb of salt in your price list.  The units conversion
that equates 16 oz with a lb will be used by GC to obtain a price for 3 oz.  If you did have a per
oz price in your price list, GC would use that directly and bypass the units conversion.

Note that to get a real price comparison across stores,  each item in your price list must have a
price entered at all stores in your database.

Working With Units Conversions
In addition to complete price lists, units conversions are key to Grocery Consumer' success in
computing the cost of your shopping list, because units vary greatly between recipes and items
available at the store.  For example, many recipes call for tablespoons or cups of sugar yet what
you buy at the store is a 5 lb bag of sugar.  Another example is milk.  Many recipes use a cup or
two of milk yet what is available at the store is gallons, half gallons, or quarts.  All this is made
simple by a units conversion table built into GC that you can (and should) add to.  The more
units conversions you have (max = 1900), the greater the percentage of your shopping list that
you will be able to cost out.

Note that volume conversions tend to be generic (applicable to any item), while mass or weight
to volume (or vice versa) conversions tend to be item-specific due to the variable densities of
food items.  It is perfectly acceptable (even desirable) to use generic mass or weight to volume
conversions, provided you realize that not all foods have the same specific gravity (i.e., density),
and the quantities that will be priced or combined in a shopping list will be estimates rather than
exact quantities.  For canned items, the volume to fluid oz conversion using the specific gravity
of water is very accurate.  Obviously, for some dry items like flour the use of a weight to volume
conversion based on the specific gravity of water must not be used.  Usually the use of generic
units for dry items is not that unreasonable for costing out a shopping list. The price comparison
will still be consistent across stores even though the price was estimated with a generic volume
to mass conversion.  Examples of some item-specific and generic unit conversions are:

	item      	unit 1	  =	qty	unit 2
	* 		gallon 	  =	16 	oz		(generic conversion)
	* 		gallon 	  =	4 	quarts			"
	* 		gallon 	  = 	1 	gal			"
	*		tbsp	  =	3 	tsp			"
	salt		oz	  =	2	teaspoons	(item-specific conversion)

where the * is a wild-card character indicating that the generic conversion is valid for any item.

A units conversion need only be entered once for a pair of units.  That is, if you have a
conversion that says a gallon = 4 quarts, you do not need another one that says a quart = 0.25
gallon.

Expanding Units Conversions
Use the Expand All... option (under the Options menu), to recursively check all conversions you
have on file to see if there are any combinations that could be developed that you have not yet
included.  For example, you have a generic unit that converts cups to gallons and another which
converts tablespoons to cups.  However, you do not have a conversion from tablespoons to
gallons.  Such combinations are important for GC to develop a full cost of every shopping list
item since many recipes use small quantities like tablespoons yet store quantities are much
larger, like bag (5 lb) or gallons, etc.

The Expand New toggle under the Options menu (default is checked, or ON) allows a recursive
check for new conversions using the one you entered each time new conversion is entered.

A word of caution:  Using Expand All to expand your conversions table can increase by a factor
of two or three the number of conversions your shopping list contains. Thus, after one or two
expansions you can easily exceed the maximum number conversions that can be kept on file
(1900).  Use this button judiciously.  Of course, if you decide you do not like all the new
conversions that were added to the list during an Expand All event, press Cancel and no
changes will be saved.  The more units you have in this list, however, the more likely a shopping
list item will be able to be matched against a price list item for the shopping list cost calculation.

Working With Coupons
A coupon database can be maintained on GC for use in reducing your shopping list cost.
GC will check to see if a shopping list item matches a coupon item and will flag this for you.  GC
does not adjust the cost of the shopping list for coupon discounts.  Coupon entries can be sorted
by item, by expiration date, or by discount amount.  Data entry is supported with a droplist that is
a combination of the ingredient and misc item droplists.

Printing
You can print virtually any of the information that Grocery Consumer manages.  This includes
the cost of the latest Shopping list at various stores, a grocery list by aisle at the various stores,
the latest Shopping List, the latest Menu, any or all of the recipes in your recipe database, any of
the ingredient droplists (ingredients, units, preparations), your units conversions, and the
miscellaneous item droplist.  Select Print... on the File menu, then select one of the print menu
options and press Proceed, or simply double click any of the options.  If you select Recipes.., you
will be prompted for which recipes to print.  Please note that the Shopping List only gets
alphabetized during the editing process, so if you want it alphabetized, Edit Shopping List... and
Save Changes prior to Printing.

Program Limits
                                                     min #      max #
stores:
#stores                                              0          20		
#items on price, aisle list                    1          unlimited

menus:
# days in menu period                         1          28
# recipes per menu day                       0          12
# recipes per meal                              0          4

recipes:
# recipes in database                          1          400
# ingredients per recipe                       1          15

shopping list:					
# items on shopping list                      1          1000
# misc. items in droplist                      1          unlimited

units conversion table:
# conversions			         1          1900
	
ingredient droplists:
# ingredients in droplist                       1          unlimited
# units in droplist                                1          unlimited
# preparations in droplist                     1          unlimited

string lengths (# characters):			
	recipe name                           1          30
	recipe contributor                    1          20
	contributor city, state              1          30
	recipe ingredient                     1          35
                 unit of measure                 1          20
                 quantity                            1           6
                 preparation                        1          20
	recipe directions                     1          600
	miscellaneous items               1          35