GRECIPES
Konstantin <grecipes@konmal.de>
08/05/2005

NAME
SYNOPSIS
DOWNLOAD and INSTALLATION
DISTRIBUTION OVERVIEW
USAGE
Overview
Import

      Recipes encoding
      Importing directories and archives of recipes
    Query
      Query by title
      Query by recipe IDs
      Query by expression

Export recipes
Editing recipes
Deleting recipes
Statistics
HELP and VERSION
MOTIVATION
HOW DOES IT WORK (INTERNALS)
ENVIRONMENT VARIABLES and CONFIG FILES ROAD MAP

NAME

grecipes is a recipe management program.

SYNOPSIS

grecipes (a better name is still to be found) is a recipe management program. It (as for today) allows to import MealMaster recipes, query a cookbook and output recipes as simple listing/in MealMaster format. It is a command line program, but it will have a GTK GUI too (look for ROAD MAP below).

DOWNLOAD and INSTALLATION

Download one of of:

static-linked executable and documentation are at www.konmal.de/grecipes/grecipes-0.2.1.static.tar.bz2
RPM built for SUSE 9.2 www.konmal.de/grecipes/grecipes-0.2.1-suse92.i586.rpm
Source RPM www.konmal.de/grecipes/grecipes-0.2.1-suse92.src.rpm
source and documentation www.konmal.de/grecipes/grecipes-0.2.1.tar.bz2

To use grecipes, the simplest way to install as static-linked executable or user RPM.

For installation instructions for all variants, see INSTALL file of distribution, also at www.konmal.de/grecipes/INSTALL

DISTRIBUTION OVERVIEW

Besides of executable, distribution of grecipes contains following files:

README (ASCII equivalent of this page)
man page grecipes.1 (man equivalent of README)
INSTALL (how to install this software)
ANNOUNCE (what's new in this release, plans for next release)
HACKING (what software I use to develop grecipes)
ChangeLog (internal changes of software, mostly for developers)
COPYING (copyleft aka GNU public license version 2)

USAGE

Overview

You must already have some recipes in MealMaster format. You import it into a grecipes database. Then you can query very effectively the database for recipe title, ingredients etc. Query results can be listed in simple column-wise format or exported as a MealMaster file.

For all operations beside of -h (--help) and -V (--version) you need to give a file name of the database file with -d (--database) option. Let say, you will store all your recipes in your home directory under recipes.db. At first time you give the database file name, the database will be created. Afterwards the database will be re-used.

Import

To import some MealMaster files, gives their names after -i (--import) option, like:

grecipes -d ~/recipes.db -i cookies1.mmf cookies2.mmf

You can give an import comment with -c (--comment) option, like:

grecipes -d ~/recipes.db -c "Wanna try this!" -i cookies1.mmf cookies2.mmf

At the more or less up-to-date PC, grecipes imports about 500 recipes per second. So depending on the amount of the recipes you'll give to it, you'll have to wait a moment or a minute or ten.

The import routine tries to be very tolerant and take some quirks of MealMaster format into account (I tested it with about 100,000 recipes). There should be no import errors normally.

Recipes encoding

Internally, all recipes (titles and texts and ingredient names and so far) are stored as UTF-8 (if you don't know what it is: it is the encoding which allows letters of all world languages be stored side-by-side). So you can mix Spanish recipes with German "gutbÃ¼rgerliche KÃ¼che" and russian Ð¿Ð¸Ñ€Ð¾Ð¶ÐºÐ¸ all in the same database.

The price for this is that recipes have to be converted into UTF-8 encoding before they can be imported. But don't worry, grecipes converts the input for you, so you don't have to fiddle about with your input files. The only thing you have to know is the encoding of recipe files. For USA, it would be ASCII. For Europe, it is probably ISO-8859-1 (if the recipes are from your friend using a Linux box), or CP1251, if you fetch recipes from WWW. Assuming the worst case where you have no idea about encoding of it - just give your data to grecipes. By default, it tries to guess encoding of the data. If it fails, or you do know the encoding, give it with the -E option, like:

grecipes -d ~/recipes.db -i cookies1.mmf cookies2.mmf -E CP1251

Importing directories and archives of recipes

Now importing some files is easy. What if you have a directories full of recipe files, or worse yet, of recipes archives (like grandma.zip, christmas.tar.gz etc). For sure, you can use some clever UNIX commands to extract all files, find them and give it as input to grecipes. As for me, I always forget the syntax of all this clever commands. And I don't like to cleanup the disk afterwards. Wouldn't it be cool to import recipes recursively from directories, treating archives as they were directories? Well, you can it now. Just give the pathnames of directories/archives. grecipes knows how to read data from following archives:

You can mix the import of files, archives and directories. Of course, encoding guessing and auto-converting recipes to UTF works with all kind of input. The given encoding wil be applied to all given files. Encoding guessing is applied to every file individually.

grecipes -d ~/recipes.db -i cookies1.zip cookies1.mmf grandpa/ -E CP1251

Query

Now that you've got some recipes, let's query them. The output of any query is a listing of recipes in simple format, like:

It is to give an overview of results, not to output the whole recipes. If you'd like to get the complete cooking instructions, use -e (--export) option to export results of a query in MealMaster format.

The listing goes to standard output, you can either redirect it to a file with

.... > list.txt

or use -o (--output) option to write into given file.

Query by title

The simplest query is by recipe titles with -T (--recipes-by-title) option. You give a wild-card string matching a recipe title and grecipes lists matching recipes.

In the wild-card expression, * matches any number of characters, ? matches exactly one character. Anything else matches itself.

Matching ignores the case of title if a matching string is all lowercase. Matching takes a title as it is if a matching string contains some uppercase letters.

Examples

Search for all recipes containing "cake" somewhere in title, ignoring the case:

grecipes -d ~/recipes.db -T "cake"

Search for recipes where title begins with "Cake":

grecipes -d ~/recipes.db -T "Cake*"

Search for recipes where title contains "cake" and "apple" in title:

grecipes -d ~/recipes.db -T "cakeapple*"

and

grecipes -d ~/recipes.db -T "applecake*"

Tip 1: If default listing has too many fields for you, you can use the "cut" command to pickup some of them, like:

grecipes -d ~/recipes.db -T "cake" | cut -d "|" -f 1-3

Tip 2: to count a number of recipes, use wc -l command, like:

grecipes -d ~/recipes.db -T "cake" | wc -l

Using fgrep or sed or other UNIX commands, you can further reformat or refine query results.

Query by recipe IDs

Another query is by recipe IDs with -I (--recipes-by-id) option. You just give recipes numbers for it.

Example

List recipes with numbers 1,10,20:

grecipes -d ~/recipes.db -I 1 10 20

Note that -I option comes at last and all arguments afterwards are treated as recipe IDs. Wrong IDs are silently ignored.

Easy? So let's start with something more interesting: pseudo-query language.

Query by expression

As I cannot imagine all queries you need you can make it up yourself with -Q (--recipes-query) option. The query consists of two-letter tokens and matching/comparison operation for it.

Following tokens are available:

TI - recipe title
CA - recipe category
IN - ingredient name
FI - import file name
ID - recipe ID

You can use following within a Q-expression:

# - stands for "matching"
>,<,>=,<= - string comparison
AND, OR, NOT operations
combine sub-queries with ()

Literal strings should be enclosed in single quotes, not double ones.

There must be no spaces between recipe token, an operation and an operand.

Internally, tokens are replaced by corresponding SQL statements. Expect weird errors pretty fast if you don't follow these rules! Note that you can as well use SQL statements directly. But it probably goes beyond the scope of this manual.

Examples

Let's start with out title example, now with -Q option. Search for all recipes containing "cake" somewhere in title, ignoring the case:

grecipes -d ~/recipes.db -Q "TI#'cake'"

It is necessary to include a query in double quotes to protect single quotes and stars from being eaten by shell.

Search for recipes where title contains "cake" and "apple" in title: Now we need only one query for this:

grecipes -d ~/recipes.db -Q "TI'cake' AND TI'apple'"

Now using category: let's find recipes which are titled as cake, but doesn't belong to the cake category:

grecipes -d ~/recipes.db -Q "TI'cake' AND NOT CA'cake'"

And now we are looking for recipes which are either titled as "cake" or belong to category "cake" or imported from directory/file called "cake":

grecipes -d ~/recipes.db -Q "TI'cake' OR CA'cake' OR FI#'cake'"

Export recipes

To export recipes, use -e (--export) option together with a query. Without any query, nothing will be exported!. Export follows to standard output, if you don't use -o (--output) option.

Editing recipes

There is no direct way to edit recipes. The workaround is to export recipes you want to edit into file, delete them from the database, edit the file and import it.

Deleting recipes

To delete some recipes, give some recipe IDs after -d (--delete) option. You can get recipe IDs from some query like:

grecipes -d ~/recipes.db -Q ...| cut -d "|" -f1 | xargs grecipes -d ~/recipes.db -D

If you want to delete all recipes, just remove the database file.

Statistics

To get a couple of numbers about your recipes, use -s (--statistics) option.

HELP and VERSION

-h(--help) gives a short help about grecipes options.

-V (--version) gives a version number of grecipes, SQLite version and internal encoding and a character used for matching queries with -Q option, like:

grecipes - recipes management software - version 0.2.1 SQLite version 3.0.7
GLOB char is #
Max. number of ingredients per recipe is 100

MOTIVATION

Well, I couldn't find a nice-working-fast-lightweight recipe management program. So I decided to write one. A good overview of available recipe management packages is available at http://mango.sourceforge.net/links.

Most programs I have tried either require a MySQL installation (which is nonsense for desktop applications IMHO) or have some weird software requirements or use some text format to store recipes and therefore painfully slow or crash at large imports.

I will try to settle down the database scheme and performance questions before GUI will ever start.

HOW DOES IT WORK (INTERNALS)

grecipes use sqlite (www.sqlite.org) to store the recipes. So it utilizes the power of full-featured SQL database without having the administration overhead of classical server-client data management.

It is written in C, leaning to the (later) GTK-based GUI. So I use glib2 from the beginning on.

It will use libxml2 to handle XML-based import/export and probably to create reports.

ENVIRONMENT VARIABLES and CONFIG FILES

none so far.

ROAD MAP

Every release is accompanied by ANNOUNCE-<Version>. The ANNOUNCE file describes changes in the current release.

Features and Goals for next releases:

0.2 - first public release:

import MealMaster recipes, query recipes, export MealMaster format.
simple documentation.

Goal: to make the project public and find a good name for it.

0.3 - deliver more basic functions

internalization/localization
handle import file encoding, so DOS-coded input will be handled transparent for user
attach/get photos for recipes
make use of libxml2 -> RecipeML import/export
other import/export formats: RezKonv, BS...
more sophisticated queries: duplicates searching...

Goal: fix the database scheme, pickup good ideas for future development, get bugs reports.

0.4 - more functionality

gnome-vsf for import files, so zipped MM recipes can be loaded directly
rlib reports -> txt, HTML and PDF export OR pandalib for PDF reports

Goal: get stable, feature-complete command line release.

0.5 - first GUI release.

Goal: get the overall GUI design and get feedback for it.

Ideas for in between:

play with libsvm (support vector classification, regression, and distribution estimation) /dbacl (Bayesian text classifier) -> classify recipes, propose recipe categories and have fun etc

1.0 release - hurray!

Have fun!

Konstantin <grecipes@konmal.de>