The CuttingBoard Application

The CuttingBoard application is a recipe manager, nutrition tracker, and meal planner (think food, brewing, mixed-drink, ...) that offers:

Storage of your recipe collection under your control on your equipment preserving your privacy (no cloud-based links that can change, disappear, or fall behind a pay-wall at some inopportune time),
Data entry via text entry and XML file import,
Convenience: the ability to search through your collection via foods and keywords to quickly find what you need,
Portability: the ability to save your recipes and other data in XML-formatted files for migration and backup,
Definition and remote retrieval of nutrition information on a food / food product basis (that can then be applied to recipes, meals, and average nutrition per time span),
Calendar-based meal-planning,
Creation of a knowledge base of notes per topic organized via a user-definable hierarchy,
The ability to entertain and motivate not only via a user-customizable greeting-quote-at-launch capability, but also via a few remaining bugs that await you since this highly-functional piece of artwork is still a prototype under construction.

Theory

A word concerning this help document format.

Objects internally managed by the application, and changable by the user, are italicized for emphasis: Recipe, nutrition, meal.
Modifiable attributes (think managed object properties) are of the form: Category, descriptor.
Named GUI widgets (e.g. a particular combo box, panel) and GUI option names or values are of the form: Recipe edit panel, source combo box, match all option, Vegan.
Navigation is presented as a stepped format: tools > export all.
User input requiring strict adherence to a predefined format or order: 1.0 recipe Nigel's Scones.
Application output is represented as: Please don't ever do that again.

Concepts

Architecture

All internal objects must have a unique descriptor that it shall be known by for purposes such as expedient database lookup and no-hassle car maintenance.
The application internally defines certain collections of words (or phrases) as keywords.
1. Keywords support:
  - user actions (e.g. search),
  - accurate parsing of human text (e.g. ingredient-line interpretation),
  - efficient database lookup via reference-links that may exist between internal objects.
2. Keyword values are grouped per type (or class). Here are a few examples keyword class applicability.
  • Recipes use
  
  Food Unit, Category, Cooking Style, Course, Cuisine, Diet, Dish Type, Effect, Occasion, Rating, Seasonal, and Custom (one user-customizable class).
  
  • Ingredients use
  
  Attribute, Food, Food Unit.
  
  • The application uses
  
  Food, Food Unit, Nutrient, Source.
3. Quite a few keywords are pre-defined by the application. The user may add new keywords and modify existing ones. Certain pre-defined keywords that are critical to proper operation are labelled as system-defined and may not be deleted (and some of their properties may not be modified by the user).
4. Tags are descriptive values that can be assigned to a recipe or ingredient to help describe your collection.
  • Tag values are available from the following keyword classifications
  
  Attribute, Category, Cooking Style, Course, Cuisine, Diet, Dish Type, Effect, Occasion, Rating, Seasonal, and Custom (a user-customizable class).
  
  • Tag examples
  
  Dinner, Dairy, Vegan, Birthday.
  
  Look at the combo box values in the Description > Classy section of the recipe edit panel for more examples.
XML-based files are used to import and export application data. Trade them with your friends (like baseball cards).
1. You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
2. You can use your backup XML files to repopulate a fresh database (e.g. if you decide to change or reinstall the hosting machine).
Conversion profiles may be defined that list equivalent amounts of a foodstuff (among dissimilar units) that can be used to perform conversions (think meal portion vs recipe yield). More on this topic can be found later in this opus.
Nutrition
1. Displayed nutrition shows both an absolute amount and the DRI percent for available nutrients. The DRI percent is based upon the user's default characteristics (e.g. age, group, activity level) that are specified at the preferences panel. A nutrition summary displays only six common nutrients (Calories, Fat, Cholesterol, Sodium, Carbohydrates, Protein).
2. With respect to recipe nutrition:
  - A recipe's nutrition data:
    - is displayed in the nutrition facts panel and provides nutrient, mineral, and vitamin amounts on a per serving basis,
    - is only available after nutrition construction is performed per ingredient via the food query panel and the nutrition construction panel,
    - is displayed as a nutrition summary via the recipe card panel.
  - Three different sources of nutrition data may be used and applied to recipes for meal-planning purposes:
    - user-defined for a specific food,
    - user-defined for a nutrition profile for a given type or product of a food (e.g. general flour, Biff's ketchup),
    - dynamically retrieved from a source (e.g. USDA FoodData Central web site) via application-generated, on-demand HTTP requests.
  - Once nutrition has been compiled for all of a recipe's ingredients, retention and / or yield factors may be applied to improve the accuracy of the composite nutrition when the preparation or cooking methods required weren't already accounted for in the selected food's nutrition.
    - For example, for a dish of fried potatoes, where the ingredient is raw, whole potatoes, and the selected nutrition from the source is for raw, whole potatoes, then one may wish to apply two yield factors at the nutrition construction panel: a) one for raw, whole potato where the prepartion method is pared, and b) one for pared potato where the cooking method is fried. This has the effect of adjusting the amount of the final dish (the yield) due to loss (or gain) of food mass as a function of the preparation and cooking methods.
    - Loss (or gain) of nutrients (e.g. minerals and vitamins) may also occur as a function of the cooking methods utilized. Retention factors may be applied to improve the accuracy of the composite nutrition when the selected nutrition compiled for the dish doesn't already incorporate the cooking methods utilized.
    - In summary:
      - Application of a yield factor is typically useful when volume adjustment is required for a dish given a loss / gain of a liquid (e.g. water):
        a cooking method is applied (e.g. baking, frying),
        
        a preparation method is applied (paring, coring, skinning) that sheads unwanted portions,
        
        when one is calculating nutrient amount per 100 g sample in conjunction with nutrient retention factors and preparation/cooking method(s). The nutrient aggregation that the application performs in the Nutrition Construction panel is for the final dish as a whole (and not "per sample").
      - Application of a retention factor is typically useful to incorporate the loss / gain of a nutrient (other than water) that occurs given:
        a cooking method is applied (e.g. baking, frying),
        
        in theory, some chemical reaction that occurs during a preparation method (ingredient mixing, oxidation).
      - Note that nutrition data derived from lab analysis of a sample provides the most accurate summation of the nutrients available from a food. But given the prohibitive nature of using that process (time, expense, recipe and ingredient variability), this application's nutrition construction (even with judicious application of retention and / or yield factors) provides only an approximation of what nutrient amounts are available from your latest pièce de résistance. Better the knowledge of an approximation of truth, rather than the deliberate practice of cluelessness.
3. With respect to meal nutrition:
  - A meal's nutrition summary, as displayed in the calendar, meals, and meal edit panels, is updated when:
    - changes to any of the meal's servings are saved (e.g. a serving's recipe or portion),
    - changes to any of the following recipe attributes are saved: yield, serving size, new nutrition data.
  - A meal's complete nutrition (not a summary), or the nutrition of a whole day's worth of meals, is available as a pop-up accessed via the corresponding calendar entry.
A note system is provided (for those of us who have the memory of a goldfish) allowing for food-, nutrition-, health-related information to be stored and quickly accessed, where each note is represented in a customizable table form and organized per topic in a hierarchical fashion.

Usability

Don't forget to hit the green save button at the end of an edit session for a particular internal object. Otherwise Liza, you're just practicing for the show.
When the user focuses on a recipe or unit combo box control, the user may type-in filter characters that will limit the number of drop-down entries shown. Once the desired entry is observed, it may be selected.
An entry in a collection of internal objects (displayed in tables, hierarchical trees) has a context menu (accessible via a secondary mouse button single-click) allowing quick access to frequently used actions.
A compound recipe references another recipe as at least one of its ingredients. Whereas, a simple recipe has only foods specified for its ingredients.

Behavior

XML Importation

When importing internal objects from XML files:
1. You may import from the same filename any number of times, but only those objects which are not already present in the application (per their unique descriptor) will be assimilated. Those already present in the application are not updated.
2. All objects that are successfully parsed from the XML file are automatically saved in the database and are immediately available within the application with the exception of recipes.
3. Imported recipes are listed in the import tab (a staging area) where the following actions may be performed.
  1. Once those selected are saved to the application via the save-imported-recipes button, they are removed from the import tab and are listed in the browse tab.
  2. A recipe can be viewed via its recipe card or edited (e.g. renamed) before being saved. So if you're not pleased with, say, the resultant ingredient dissection, you may realign the result to better fit your personal worldview.
  3. Any recipes not saved from the import tab are discarded upon application exit.
  4. The error column lists the number of parsing errors found for a recipe when the XML file was processed. You may wish to pursue corrective action such as:
    - Delete the recipe, fix its data in the XML file, and import that file again, or
    - Import another XML file that contains any missing recipes referenced as ingredients by the impaired recipe.
    - Selecting multiple recipes that reference each other as ingredients and performing a save (sometimes more than once) can work since the application attempts to save what it can during each successive iteration. Just no circular references, please, because that's just malicious.
    - If the number of recipes in the import tab doesn't diminish after a save or two, then there's no more air in the tires, Axel.
  5. Deleting a recipe from the import tab will also automatically delete any other recipes in the import tab that use that recipe as an ingredient.
4. If editing XML files before an import, please use full words rather than abbreviations for any type of unit (e.g. fluid ounce, not fl oz; ounce, not oz).

Retention and Yield Factors

Retention and yield factors may be applied during nutrition construction to adjust the edible's nutrient values as a function of any preparation and/or cooking methods applied. The following table identifies allowed behavior.

Retention and Yield Factor Behavior
Rule	Retention Factor (applied at ingredient level)	Yield Factor (applied at recipe level)
Multiple factors allowed	y	y
No factor is allowed	y	y (when factor not available at recipe)
When last factor removed, default used	n/a	y (when factor is available at recipe)
Factors can be per ingredient	y	n
Add/remove order is irrelevant	y (all applied per nutrient per ingredient level)	y (all applied per nutrient total per recipe level)

Updates

During an automatic upgrade (where the user-initiated update check was started via Help > Check for update menu item), the following steps will occur (in sequence) when an available update is detected and the user selects "yes" at the Proceed with update? alert panel.

The zipped file is downloaded from the application server to the client's host and its content is extracted to the {ArtifactDirectory}/update directory. This may take many seconds to complete.
The user is notified, via a note within the CuttingBoard panel's status bar, that the upgrade will occur once the application is restarted.
The user exits the application.
The user may delete the database directory (and nothing else) if a fresh start is desired (with a corresponding loss of any preexisting user data).
Upon next application start, the new executables are copied from the {ArtifactDirectory}/update directory to the installation directory and begin their execution.
If, upon restart, no existing database is detected, a fresh one is generated with its initial system data (typically requiring many 10s of seconds). Otherwise, the old database will be gleefully used (without any loss of user data) when no database schema change has occurred between the previous and new versions.
The user is notified, via a note within the CuttingBoard panel's status bar, concerning the resolution of the upgrade.

Database Regeneration

A database regeneration is required when a database schema change has occurred between the application's current installation version and a new version. The user is made aware of this condition either by:

Reading the release notes at the application server for the version of interest, or
After performing a check for update at the application, a "Regeneration Required!" phrase is observed in the text of the Proceed with update? alert.

Note:

This process is only required when the database schema has changed for the new version and the existing data has to be migrated into the new paradigm. If no database schema change is required by the new version, the upgrade only consists of the download, extraction, and executable copy during the application restart.
The ServerDirection preference may be disabled by the user via the preferences panel when the user wishes to manually enact any migration necessary (see the following section) to support an application update that documents a schema change; otherwise, when the preference is true an automatic regeneration is enacted. This automatic regeneration capability only becomes available when, at least, release v0.42.8 is already installed.
The re-importation step may take many minutes to complete if the host is slow and / or a large amount of user data exist.
The process does not migrate user modifications made to system objects that were part of the application's initial installation. Therefore, the user must reapply those customizations. This is a current annoyance that may be rectified in a future release.

Manual

If one wishes to upgrade an existing installation to a new version that includes a database schema change and preserve their existing user data, do the following steps (in order):

Perform any favorite superstitious rituals to the technology gods.
Check for an available update.
Select "yes" at the Proceed with update? alert panel.
After the download and extraction has completed, DO NOT yet exit the application unless you've already performed the next step to export your data.
Select the tools > export all menu item to export all data from the application into XML files located in the export directory.
Exit the application.
You MUST delete the database directory (and nothing else).
Restart the application and patiently wait for the database to be recreated.
In the following sequence, import any highly-cherished, previously-exported XML files (i.e. those from the first step, if you get were I'm going with this). If you haven't added any new objects to a particular class since the initial installation, there's no need to import that XML file. During an import, an object whose descriptor (i.e. name) already exists within the database is considered a duplicate and is skipped.
1. LanguageReference
2. FoodUnit
3. Tag
4. DietaryReference
5. NutrientReference
6. Nutrient
7. RetentionFactor
8. YieldFactor
9. Food
10. ConversionProfile
11. NutritionProfile
12. Note
13. Quote
14. Recipe
15. Meal

Automatic

The goal of an automatic database regeneration during upgrade is a new database with an improved data schema and a lossless migration of the user's pre-existing data without (ahem) the typical user interaction (and distress).

During an upgrade, the following steps will occur (in sequence) when the ServerDirection preference is true, a "Regeneration Required!" phrase is observed in the text of the Proceed with update? alert, and the user selects "yes".

The zipped file is downloaded to the client's host and extracted.
The user is notified, via a note within the CuttingBoard panel's status bar, that the upgrade will occur once the application is restarted.
Upon exit, an XML export of all system and user data from the existing database automatically occurs to files of the form, {name}_vX.Y.Z.xml, in the {ArtifactDirectory}/export directory where vX.Y.Z represents the application version currently active.
Also upon exit, the existing database directory is renamed to {ArtifactDirectory}/database_vX.Y.Z.
Upon next application start, the new executables are copied from the {ArtifactDirectory}/update directory to the installation directory and since no existing database is detected, a fresh one is generated (patience young grasshopper).
The user's {name}_vX.Y.Z.xml data files are automatically imported (a process that may take at least 30 seconds).
The user is notified, via a note within the CuttingBoard panel's status bar, concerning the resolution of the regeneration.

Communication

Internet

Communication with the USDA's FoodData Central web site, via HTTP requests, is performed to gather nutrition data for food products per user request only when enabled by the user (see Configuration).
An embedded web browser is made available for user entertainment and is only used by the application to display help.
A user-initiated update request (Help > Check for update menu item) will query the home site of the application to determine if a newer version exists. Only if requested by the user, will the application download that newer version to the user's computer and attempt an update.
Other than what's described in the previous points, no other data is retrieved from nor sent to any other Internet site by the application for any purpose, because I'm just nice that way. Your data is your data. The application does not "phone home" any information from your computer. Those without faith can peruse the publicly-available source code at the home site of the application.

Configuration

Certain application operating parameters may be modified via a preferences panel to align the tool with your expectations.
If you'd like to retrieve nutrition information for food products used in recipe ingredients:
- Request your free personal FDC API KEY from the USDA FoodData Central web site: USDA FDC sign-up site,
- When the app's nutrition menu item is selected and the query button is first pressed for a food, you're prompted to enter this FDC API KEY key if it wasn't previously defined. A first-time configuration thingy that the application thereafter remembers. Forevermore.

Beware. Here Be Dragons

At this time (note the version number on the about panel), this application, although highly functional, should be treated as a prototype. As such:
1. It may inadvertently fall over and wheeze.
2. It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
3. It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
4. NO WARRANTY, EXPRESS OR IMPLIED. EXCEPT AS EXPRESSLY PROVIDED IN THIS AGREEMENT OR IN THE CONVEYANCE, CONVEYANCE OF THE WORKING INTEREST SHALL BE WITHOUT REPRESENTATION OR WARRANTY WHATSOEVER, EXPRESS, STATUTORY, OR IMPLIED, INCLUDING, BUT WITHOUT LIMITATION, AS TO TITLE, DESCRIPTION, PHYSICAL AND ENVIRONMENTAL CONDITION OF THE WORKED INTEREST, QUALITY, VALUE, FITNESS FOR PURPOSE, MERCHANTABILITY, OR OTHERWISE.
5. When updating to a new application version that has a database schema modification, you may wish to consider an XML-export of your data from the old version in order to have data to import into the new version as a migration policy. This may be required when the Author shamelessly changes the database schema used to save data of the application's internal objects. But if the Author really decides to flood the world and start over, said Author may even smite the XML schema used in which case you're SOL. So keep those eyes, fingers and toes nimble, boys and girls. Read the change log to be aware of feature changes. The Author intends to automatically handle said changes gracefully during an application upgrade but, ya know, stuff sometimes happens.
Inherent limitations
1. My artwork.
2. My patience with unhelpful, nonconstructive feedback.
3. If you're sloppy with units, don't expect the application to take up the slack. To be accurate, use weight units for dry foodstuffs and volume units for liquids. This not only makes your chemistry experiment more reproduceable and tasty, but also results in less unit conversion aerobatics at the food query panel when you're fishing for nutrition. Put another way, if you specify a cup of sugar and switch the recipe card measurement system to metric, don't be surprised if you're shown a value in milliliters. You asked for it, Aristotle.
4. Effort has been expended with respect to dynamically updating active panels with new data that has been saved via other concurrently active panels. Having said that, we may not be there yet in all cases. Don't see what you're looking for? Exit the panel (with perhaps a save, wink) and reenter the panel to view the latest stuff.
5. XML imports currently do not migrate user modifications made to an object that is already defined within the database (e.g. were part of the application's initial installation). An object that has the same descriptor (name) is considered a duplicate and is skipped during re-importation. The user must manually reapply any customizations made to pre-existing objects.
Features currently under consideration, but not yet available due to Author's penchant for first picking the low-hanging fruit.
1. Importation of various file formats (e.g. PDF).
2. An XML import that updates pre-existing database objects with any user modifications that exist within the XML file.

Nuts and Bolts

Application Widgets

Internal Objects

The application defines and manages a few different types of objects.

Managed Objects (MOs) are persistent (i.e., stored in a database located on your computer) and have properties (e.g. descriptor, variety, abbreviation, amount) that are modifiable by the user via the application's edit panels. These MOs are defined and categorized as follows:
1. Measurement
  1. A conversion profile defines one or more conversions between two or more equivalent portions, that are unique to a specified food or food-type.
    1. A conversion profile's portions have units of dissimilar dimension, such as:
      - weight vs. volume (e.g. 200 grams and 1 cup), or
      - where there's an arbitrary relationship to be made (e.g. batch and squares, loaf and slices).
    2. The application inherently knows how to convert between different units of similar dimension, such as:
      - weight-to-weight (e.g. pounds to grams), or
      - volume-to-volume (e.g. liters to gallons).
    3. A conversion profile is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
  2. A food unit (a keyword) is a unit of measure applicable to food (e.g. cup, not parsec)
  3. A measurement is an amount of something. Akin to portion.
2. Nutrition
  1. A cooking reference is a set of data (e.g. retention and yield factors) that may be applied to more accurately calculate nutrition for a food or recipe that undergoes some series of preparation and / or cooking methods.
  2. A dietary reference is a set of data (typically daily recommended intake levels of general food components, calories, vitamins, and minerals) that may be used as a comparison with your frenzied feeding habits.
  3. A nutrient is a substance (e.g. chemical elements, minerals, vitamins) required by organisms for health. The application can track nutrient content per food, recipe, meal, or per a day's meals.
  4. A nutrition (aka, a nutrition catalog) is a potentially large set of nutrition data (e.g. an amount of calories, minerals, vitamins, macro-nutrients, micro-nutrients) that is applicable for a specific portion of a food, recipe, or nutrition profile.
  5. A nutrition profile defines food product meta data (IDs, production, components, analysis) for the one, unique nutrition that it references.
  6. A nutrition summary is a summary set of nutrition data (i.e. an amount of calories, fat, cholesterol, sodium, carbohydrates, protein) that is applicable for a serving or meal.
3. Organization
  1. Keywords are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
  2. A tag (a keyword) is a word assigned to another managed object to label it (i.e. to describe something notable about that managed object).
4. Planning
  1. A meal is a composed of one or more servings that has its own nutrition summary and scheduling information.
  2. A serving is a portion of a recipe, that has its own nutrition summary and that is assignable to a meal.
5. Recipe
  1. A food (a keyword) is an edible plant, animal, or chemical compound that is independent of producer, manufacturer, or packaging. A food may have one or more substitutes, where each has it's own set of ingredients and may be qualified with attributes or be applicable to a particular cooking style.
  2. An ingredient defines a portion of an edible (i.e. a food or another recipe) that can have defined characteristics.
  3. A recipe is a collection of ingredients and / or other recipes with preparation instructions with defined characteristics.
6. Supplemental
  1. A note is a collection of textual points (nested under a parent topic) that can be saved in a table as a variable number of rows and user-definable columns. A topic (which has no textual points) is a parent to any number of other topics or notes, all arranged in a user-definable hierarchy.
  2. A quote capability is provided to display a random, user-definable quote in the CuttingBoard panel's status bar (at the bottom) upon application start to inspire.

Transient Objects (TOs) are not explicitly saved and are created as needed:
1. The meal-planning calendar allows meals to be created and allocated across one or more days per scheduling rules.
2. A calendar entry can be a meal entry or a day aggregator entry.
3. A meal entry represents a meal scheduled on a day or recurring across several, possibly nonconsecutive, days.
4. A read-only day aggregator entry, automatically defined in the aggregate calendar, displays the nutrition summary for all meals scheduled for that day.

External Artifacts

The application defines and manages the following external artifacts which are located on the host's file system: directories, files, database.

Directories

The application automatically creates and requires the following directories to properly function:

The 'CuttingBoard' directory, also referenced as the Artifact Directory, contains the data that the application operates upon. That data is organized within the following sub-directories:
configuration

Contains the database configuration file(s) required by the application to properly function.

database

Contains the database required by the application to properly function.

export

Contains the XML and PDF data files (e.g. *.xml, *.pdf) exported from the application.

help

Contains help files required by the application to properly function.

import

Default directory that contains the XML data files (of the form *.xml) that may be imported into the application.

log

Directory that contains application log files (e.g. app.log and app-yyyy-mm-dd.log).

update

Transient installation directory, where the zip file content was extracted to during an update, contains the files required for application execution: a Java jar file, preferences.xml file, and any launch-support scripts.

Configuration Files

While active, the application maintains a cuttingboard.lock file in the user's home directory to prohibit a user from launching multiple application instances. Just how many bullets ya need there, Tex?

The application's configuration file, preferences.xml, is automatically created (located in the directory from where the application was launched), when the application doesn't find the file already there. The file contains settings that may be subsequently changed either via text editor (when the application is not active) or via the preferences panel. These settings are categorized as follows:

Core
ArtifactDirectory

Specifies a user-configurable location, where the application's main data directory resides within which its data is persistently kept.

DatabaseCachePercent

Specifies how much of the java virtual machine memory space should be used as database cache.

Developer

A parameter that activates developer mode for, not to put to fine a point on it, developer functionality. Not intended for normal users.

DownloadUrl

From whence the application beams new incarnations of itself (but only when directed by the user).

LogLevel

Specifies the level of logging produced during execution. More detailed logging equates to a slower application.

LogRetention

Specifies the number of days to keep daily log files. Those beyond this expiration are automatically deleted.

Restart

A parameter required by the application to properly function (and which shouldn't be mucked with by us muppets).
Food Data Central Communication
FdcApiKey

Specifies the USDA FDC API KEY that is used to uniquely identify the user of the FDC service,

FdcFoodsUrl

Specifies the FDC's internet food server from which food product data may be retrieved.

FdcNutritionUrl

Specifies the FDC's internet nutrition server from which food product data may be retrieved.

ConnectionTimeout

Specifies the time to wait (in seconds) to establish a connection with a remote server.

SocketTimeout

Specifies the time to wait (in seconds) for a response from a remote server.
User-Interface
ConversionNotification

Specifies whether notification pop-ups occur during nutrition construction that describe the seriousness of any unit conversion issue encountered for the selected food product and what resolutions exist.

DisplayNumberRepresentation

Select number representation: Decimal vs Fractional.

DisplayUnits

Specifies which system of units are used within the recipe card panel: Native, Metric, or US.

Salutation

Specifies the name that the application will use to ingratiate itself to you.

ServerDirection

When enabled, allows devops personnel to force certain upgrade behavior during a client's update (e.g. to force a database regeneration).
Meal Calendar Recurrence Limits
CalendarRecurrenceDaily

Specifies the maximum number of days the event may be scheduled to repeat.

CalendarRecurrenceMonthly

Specifies the maximum number of months the event may be scheduled to repeat.

CalendarRecurrenceWeekly

Specifies the maximum number of weeks the event may be scheduled to repeat.

CalendarRecurrenceYearly

Specifies the maximum number of years the event may be scheduled to repeat.
Identifies the default recommended dietary intake records that apply to you in the Dietary Reference
ActivityLevel

Specifies your physical activity level.

Age

Specifies your age.

AgeUnit

Specifies the time unit used for your age.

Group

Specifies the group that best describes your sex / condition.

Weight

Specifies your weight.

WeightUnit

Specifies the unit used for your weight.

Media Types

The following table defines the support for the managed objects given a media type for the current application version. File names are of the form Base Filename.extension where extension is either "xml" or "pdf" as applicable.

Managed Object Media Type Support
Base Filename	Footnotes	Printer	XML file Import	XML file Export	PDF file Export
Per a group of managed objects:
ConversionProfiles	2	n	y	y	n
DietaryReference	2	n	y	y	n
Foods	2	n	y	y	n
FoodUnits	2	n	y	y	n
LanguageReference	2	n	y	y	n
Meals	2,3	n	y	y	n
Notes	2	n	y	y	n
NutrientReference	2	n	y	y	n
Nutrients	2	n	y	y	n
NutritionProfiles	2	n	y	y	n
Quotes	2	n	y	y	n
Recipes	2,3	n	y	y	n
RetentionFactors	2	n	y	y	n
Tags	2	n	y	y	n
YieldFactors	2	n	y	y	n
Per a single instance of a managed object:
"meal descriptor"	1,7	y	y	y	y
"recipe descriptor"	1,7	y	y	y	y
Available templates for these managed objects:
DietaryReferenceTemplate	4,5	n/a	y	n/a	n/a
MealTemplate	4,6	n/a	y	n/a	n/a
RecipeTemplate	4,6	n/a	y	n/a	n/a

Footnotes:

Available for a single meal or recipe export once meals or recipes are defined in the application.
Available for XML import or export of a group of those managed objects defined in the application.
That is, available once meals or recipes are defined in the application :-).
These XML-based template files are available in the import directory and may be modified to bulk-XML-import new managed object data. The files not only provide the valid syntax and format that is required for importation, but contain examples of valid sample data.
Available for one or more custom population groups and their dietary reference data.
It's suggested that you first create a few recipes / meals via the application GUI and export the result to gain familiarity with the value and dependency rules that must be followed to be successful. Otherwise, woe to you.
Each meal or recipe starts a new page when exported as PDF.

Database

The storage mechanism the application uses to persistently save the vast bulk of its data is a database. The database is configured out-of-the-box to not be bound by any sizing constraints. If the disk runs out of free space during usage, data corruption can occur. Freshly installed, the database consumes approximately 10 megabytes. The database property file (which should not be mucked with by mere mortals):

is located at {ArtifactDirectory}/database/janusgraph/je.properties, and
may be edited to customize behavior, per its Configuration in accordance with its own product documentation.

Command-line Invocation

Command-line invocation may be of the form (on a Windows OS):

"%JAVA_HOME%\bin\java" -Djava.util.logging.config.file=%CUTTINGBOARD_SUPPORT%\logging.properties -Dorg.entangledbits.cuttingboard.preferencesFile=%CUTTINGBOARD_SUPPORT%\preferences.xml -jar cuttingboard.jar >>%CUTTINGBOARD_SUPPORT%\output.log 2>&1

Application Panels

General Tips

The application, being nothing more than a mindless mass of entangled bits, uses color-coding in a select few instances to aid in communication with its human overlord as noted in select spots of this magnum opus.
When editing an object (e.g. recipe, profile, meal, keyword, nutrition) via its panel, the save button turns green upon modification to remind those easily confused that you actually have the ability to save the item when done. Because a panel exit without a save, is ... well, just futile.
Almost all combo boxes (i.e. drop-downs) are searchable (when characters are typed into the widget) to allow filtering of the data set when a large number of items are available.
User-entered data (via edit panels, XML file input) is generally allowed to pass into the application unmodified but in the following case, we make an exception (to preserve the Author's sanity):
- A backslash character, '\', is automatically removed from the text of the following Managed Object properties: abbreviation, alternate, attribute, variety, tag. Within all other properties (e.g. instruction), is it allowed.
The backslash character may be used in a comma-delimited query field of a search tab to indicate that the subsequent comma is actually part of the string to be searched upon. For instance, for a recipe search, to define that two strings be used in the search: Calorie\, Low, Anti-inflammatory
With regard to keyboard navigation within a panel:
- The tab key may be used to meander between widgets (e.g. a text field, a drop-down, a table),
- Within a panel's non-trivial widget (e.g. a table), the arrow keys are available for navigation between subcomponents (e.g. table cells).
With regard to searchable combo boxes (i.e. drop-downs that allow a text field for filtering):
- To enter the text-input mode of a searchable combo box, use these methods:
  - Perform two slow primary-mouse-button clicks, or
  - Within a table, arrow-key to the desired combo box (achieve combo box focus) and perform the following (not simultaneous) keystroke sequence: enter, tab, down arrow.
  - When not within a table, tab to the desired combo box (achieve combo box focus) and perform a down arrow keystroke.
- To navigate within the drop-down list of a searchable combo box, use these methods:
  - You can always use the ctrl-up/ctrl-down arrow keys and the enter key will then select.
  - If the list is simple and not alphabetized, you can use just the up/down arrow keys and the enter key will select.
  - In the case of some alphabetized lists that have very similar entries (e.g. nutrients), if you don't simultaneously use the control key with an arrow key, you'll achieve some wondrous auto-magical selection that you may not want.

Collection Panels

This section describes those panels that show collections of objects that are managed by the application. The CuttingBoard panel is the main panel of the application and the launch point for all other panels.

CuttingBoard Panel

Purpose
1. Provides display, search, and management of user-defined recipes and notes
Actions
1. The search tab supports searches for recipes whose descriptor, classifiers, and / or source contain the specified tags.
2. The search nutrition tab supports searches for recipes whose nutrition matches user-defined nutrient amounts.
3. The browser tab lists all recipes that may be used / modified.
4. The import tab lists imported recipes that may be selected and saved, if desired.
5. The scrape tab attempts to import (scrape) a recipe from a web-page's URL or from a file's HTML content (when that page defines or that file contains the recipe as a schema.org/Recipe type).
6. The notes tab supports hierarchical display and management of notes, presumedly related to food-like musings.
Controls
1. The status bar at the bottom provides feedback to the user concerning disposition of actions taken. Usually. If it ever turns red with a portion of an exception trace, you should swear (since your last bit of work may not have been saved) and send bags of gold to the Author. Better yet, a support email (see the about panel) beginning, "Please fix ...".
2. The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error
3. You can initiate an update request via the Help > Check for update menu item.
4. Upon the first selection of the scrape tab, initialization is started that may take a few tens of seconds to complete (as shown via its progress bar). Scrape requests may only be initiated after the completion of the scrape initialization, which prepares the deserialization (i.e. parsing) algorithm to interpret downloaded recipe datasets.
5. A scrape request may take several seconds to complete. When successful, a recipe edit panel is launched with the parsed data. You should inspect the values and correct or adjust anything as desired before hitting the save button since issues may occur due to improper data entry at the origin or even due to the application's interpretation of this free-range data. This is especially true of the recipe instruction text which may be bizarrely crafted.
6. The scrape tab's character set combo box specifies how the retrieved data is decoded. The latest HTML specification uses UTF-8; however, some sites may still have remnants based upon ISO-8859-1. If you observe strange characters in the text or unexpected amounts in the recipe ingredients, a new scrape attempt after another character set has been selected may improve your results. You’ve gotta ask yourself one question: “Do I feel lucky?”
Tips
1. From any table of recipes, you can primary mouse button double-click to see a summary of the recipe in the recipe card panel.
2. From the search tab, you can:
  1. Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
  2. Enter any number of comma-delimited words / phrases (that are not tags) to search for those recipes that include the word / phrase within either the recipe's descriptor, description, or source.
  3. Select the match all option to require that a recipe has all specified tokens (rather than at least one of the tokens when the match all option is not selected, you hockey puck).
  4. Any text entered between commas is considered a stand-alone search token. When searching via a food represented by a space-delimited words (e.g. almond extract), enter those words (without intervening commas).
  5. Entered text with no commas is considered a single search token.
3. From the search nutrition tab, you can:
  1. For whatever collection of nutrients are of interest, enter a quantity (greater than zero) in accordance with the default unit and right-mouse-click to select the Search for Recipes menu item.
  2. Recipes that match all of the criteria are listed in the search tab.
  3. Listed recipes are those that have nutrition defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
4. From the browse tab, you can:
  1. View a summary of some of the more-notable properties of each recipe.
    - The nutrition column shows "Y" if a recipe has nutrition defined and may have an appended "o" if that nutrition is outdated. Changes made to a recipe's properties (e.g. yield, or ingredient count, amount, or edible) since the last nutrition construction result in this outdated state. It's an indication that the user may wish to reconstruct and save a new nutrition data set per the latest recipe property values.
5. From the import tab, you can:
  1. Select any or all of the recipes' listed in the table and permanently save them in the database via the save imported button. Those not chosen are not worthy and will be forgotten, like some bad, fever-induced dream, when the application is closed.
6. From the notes tab, anywhere in the hierarchy under the Library topic, you can:
  1. Create a note with a unique descriptor and add salient points to a variable row table with any number of user-defined columns. There are three flavors of notes:
    - An unsourced note has a paper with pencil icon with no attribution.
    - A sourced note has a magnifying glass icon indicating that a source was added (right-click > Add Source menu item). A view source action (right-click > View Source menu item) will launch the relevant host application (e.g. web page) if the attribution was a URL (vs. a Wikipedia page for non-URL text).
    - Create a note with a unique descriptor (having no underlying table of data), and use it as a topic (i.e. folder) under which you can organize other topics or notes. A topic has a folder with pencil icon.
  2. Move the little buggers around the hierarchy as you see fit.
  3. The Library and Orphan topics cannot be removed and are required by the application for proper function.
  4. Imported notes that the application can't find / define a parent for, are located under the Orphan topic. The kind user will find these cute puppies a proper home.
  5. To delete a note's row or column, select a cell in that row or column, right-mouse click to display the context menu, and select the desired operation. If the selected cell's text is a properly formatted URL, a follow-link action (right-click > Follow Hyperlink menu item) will launch the relevant host application (e.g. web page) with that text.
  6. The title of a new or changed note will remain green until the note is saved (right-click > Save menu item). For the notes functionality, the application will currently throw any unsaved changes out the airlock when the user closes the application. There's no "unsaved changes" notification (unlike the other managed objects). Because, in space, no one can hear you scream.
7. From the scrape tab, for scraped recipes, keywords that are not predefined will not automatically be imported and applied (since you could end up with a swarm of different keywords that all pertain to the same concept). In this case it's more manageable to predefine the ones you desire and add any of those that haven't been automatically matched (during the scrape) via the recipe's edit panel that appears after a successful scrape.
8. From the scrape tab (during a recipe URL scrape), the application may encounter obfuscated HTML (i.e. purposely encrypted to disallow automated scraping). As a workaround, sometimes, using your favorite browser, you can select a "view source" option and copy and paste the unobfuscated HTML into a file on your computer and scrape that file.

Calendar Panel

Purpose
1. The meal calendar displays and allows time-management of meal entries to support meal-planning. A meal entry presents its nutrition.
2. The aggregator calendar provides read-only display of day aggregator entries. Each day's aggregator entry presents the collective nutrition for that day's meals.
3. A nutrition summary is displayed in the calendar entry whereas all available nutrition is available via its context menu.
4. The agenda view provides a look-ahead and look-behind list of meals.
Actions
1. To add a meal, primary mouse button double-click in the meal calendar at the desired start time.
2. To remove a meal, select it and depress the delete key.
3. By right-clicking on a meal, you can select the following options:
  1. View nutrition displays a read-only summary view of the meal's nutrition.
  2. View servings displays a read-only summary view of the meal's servings.
  3. Edit schedule displays a scheduling edit view where meal scheduling data may be modified (e.g. starting date and / or time, location). A recurrence rule can also be applied or modified. The rule defines multiple calendar entries that repeat on specified days across various time spans.
  4. Edit meal launches the meal's edit panel to allow its serving data to modified.
  5. Print meal prints the meal. Doh!
  6. Delete Meal permanently removes the meal and the day's aggregate nutrition is automatically updated as a result.
4. Only the View nutrition option is available for an aggregator entry. It displays a read-only summary view of the nutrition for that day's set of meals.
5. To change the look-ahead / look-behind time span for the agenda view, right-click and follow your instincts.
Controls
1. A meal entry created at the meal calendar is also displayed at the meals panel where it can have its name changed and servings added.
2. If you're easily amused, launch both the calendar and the meal panels for a given meal and observe how changes to the meal's servings and nutrition are reflected in the nutrition summary of its corresponding calendar entry even before the data is saved. Note that all other serving / nutrition data in the calendar that is based off the meal always reflects what is actually saved in the database.
3. meal entries are viewable for a given day, week, month, or year time period.
4. When a recurrence rule is enacted for a meal, the calendar's day view (and only its day view) will display each entry's meal name with an instance number (e.g. #1, #2, ...) appended. Because all snowflakes are unique.
5. Concerning calendar entries:
  1. The application only saves entry data from the meal calendar.
  2. Aggregator calendar entries are auto-magically created when at least one meal entry exists for that day.
Tips
1. Scheduling
  1. The non-custom selections (right-mouse-click > Edit schedule > Repeat combo box) have, by default, the following number of repetitions: Every Day (7), Every Week (52), Every Month (12), Every Year (10).
  2. When crafting a custom recurrence rule, don't forget to specify some form of time span termination (e.g. an end date, maximum number of occurrences). If not specified, the application automatically enforces its own maximum limit for number of repetitions as defined in the preferences panel. Otherwise, you'd regret it. Mwahahahaha.

Foods Panel

Purpose
1. Provides display and management of both pre-defined and any new, user-defined foods
Actions
1. Use the add button to define a new food.
2. Primary mouse button double-click an existing food to edit its characteristics.
3. Secondary mouse button single-click an existing food and choose the construct nutrition option to search for and apply a particular food product's nutrition to the food.
Controls
Tips
1. Saving nutrition for a particular food allows that nutrition to be selectable when building a recipe's nutrition at the food query panel.

Substitutes Panel

Purpose
1. Provides display and management of all substitutes that exist for all foods.
Actions
1. Use the add button to define a new substitute for a new food.
2. Primary mouse button double-click an existing food substitute to edit its characteristics.
Controls
Tips
1. Keep your cake moist by eating it in one sitting.

Tags Panel

Purpose
1. Provides display and management of both pre-defined and any new user-defined tags.
Actions
1. Use the add button to define a new keyword.
2. Primary mouse button double-click to edit the characteristics of a particular tag.
3. Secondary mouse button single-click and select an option to add, edit, or delete a particular tag.
Controls
Tips
1. Use the foods panel for foods management.

Tree Panel

Purpose
1. Displays all nutrients or food units as a hierarchical tree where the selected item's data is presented via table.
Actions
1. Define a new keyword via the add button.
2. Search for a case-sensitive word or fragment via the search text box.
3. Open or close the entire tree hierarchy via the expand / collapse radio button.
Controls
1. A primary mouse button double-click will open / close the selected branch.
Tips
1. If no one comes from the future to stop you from doing it, then how bad of a decision can it really be?

Meals Panel

Purpose
1. Provides display, search, and management of user-defined meals.
Actions
1. The search tab supports searches for any meal whose descriptor contain the specified tags and / or whose start date falls between any specified start / end dates(s).
2. The meal tab lists all meals that are available.
3. Primary mouse button double-click to modify the characteristics of a particular meal.
4. Secondary mouse button single-click to access a context menu providing per meal actions.
Controls
Tips
1. From the search tab, you can:
  1. Enter any number of comma-delimited words to search for a set of meals.
  2. Select the match all specified words option to require that a meal must match all specified words (rather than just any combination of the words when not selected).
2. Concerning a meal's start date and recurrence rule:
  1. They are read-only at the meals panel and are not changeable at the meal panel.
  2. They may only be changed at the calendar panel (which is used for meal-planning).
  3. The initial value for the start date is the time of meal creation allowing for quick access to the entry at the meal-planning calendar (from whence it may be changed).
3. The meal's displayed nutrition is read-only and remains zero-valued until servings are added with assigned portions and recipes that have their own nutrition defined.

Profiles Panel

Purpose
1. Provides display, search, and management of user-defined conversion profiles and nutrition profiles.
Actions
1. The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
2. The conversion tab lists all available conversion profiles that may be applied or modified.
3. The nutrition tab lists all available nutrition profiles that may be applied or modified.
4. The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
5. Primary mouse button double-click to modify the characteristics of a particular profile.
Controls
Tips
1. From the search tab, you can:
  1. Enter any number of comma-delimited words to search for a set of profiles.
  2. Select the match all option to require that a profile must match all specified words (rather than just any combination of the words when not selected).

Quotes Panel

Purpose
1. Provides display and management of any user-defined quotes
Actions
1. The add button, add menu item, or a well-placed primary mouse button double-click will add a placeholder row at the beginning of the unsorted table to support the new quote's data.
2. There can be only one placeholder row (identified by the quip, "Please enter a quote ...") defined at a time. Once the quip portion of the quote is uniquely defined, you may add another placeholder.
3. When a row is selected, a single-click places a table cell into edit mode to support a change. When the cell is exited, the quote is automatically saved.
4. A delete permanently removes the selected quote.
Controls
Tips
1. No color change hints for edits are provided since updated quote fields are automatically saved.
2. A child of five could understand this. Send someone to fetch a child of five -- Groucho Marx.

Editor Panels

This section describes those panels that are available to edit an object managed by the application. Notes and quotes may only be edited in-place via their dedicated tabs in the CuttingBoard panel.

Conversion Profile Panel

Purpose
1. Allows definition of conversion data for a food type or product that is saved as a named profile and may be used to convert units used by recipes and meals.
2. Allows a yield factor to be automatically calculated for a recipe when an ingredient unit is not compatible with either a gram or liter unit.
3. Can greatly improve accuracy during nutrition construction.
Actions
1. Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified food type or product.
2. Copy the equivalent portions from another conversion profile and update as desired.
3. Attribute your conversion data to its source if your nicking it from some other world.
Controls
Tips
1. The descriptor of a conversion profile must:
  1. be unique, and
  2. exactly match a food type or product descriptor that is used in recipes.
2. To remove, highlight one or more portions and depress the delete key.
3. Imported conversion profiles will automatically be assigned to a food with the same name.

Keyword Panel

Purpose
1. Provides definition and management of any single CuttingBoard keyword. The type of keyword (food, food unit, nutrient, or tag) is identified by the title of the panel.
Actions
1. Add, edit the characteristics of, or delete a keyword.
2. The characteristics defined and available for change are a function of the classification (type) of keyword.
Controls
Tips
1. When modifying a food:
  1. You can add nutrition data which can later be used as a source during construction of nutrition data for a recipe.
  2. You may copy the nutrient entries from multiple nutrition profiles as long as no nutrient is duplicated across any of those profiles. When a duplicate is detected, none of the nutrient entries for the offending profile are copied.
2. Food units and nutrients are partitioned as either user-defined or system-defined with the following limitations:
  1. System-defined keywords are not deletable (given their mission critical nature)
  2. Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
  3. Once a food unit is created, whether user- or system-defined, its descriptor and derivation properties cannot be modified. To change a property of a user-defined food unit, delete and re-create the food unit with the desired property values.
  4. Specify derivation values only when the new food unit should be based upon another, pre-existing food unit (e.g. a cup is 1/16 of a gallon). For stand-alone food units (e.g. loaf, stalk, rack), no derivation should be specified.
  5. Pay particular attention to specifying the correct derivation values at creation (i.e. before using the unit as a amount or portion in any managed object), since managed objects use a copy of the food unit (not a reference). Any change of derivation value by the user (via a delete and re-create action) doesn't change the continued usage of the old version of the food unit previously assigned in managed objects (e.g. recipes, ingredients, conversion profiles, nutrition) and requires the user to re-assign the new unit to the affected managed objects (and possibly recalculate any downstream nutrition).

Meal Panel

Purpose
1. Provides definition and management of a meal.
Actions
1. Add a serving, with a meal-unique descriptor for a specified portion of a selected recipe.
2. Copy the serving entries from another meal and update any serving descriptor, recipe, portion as desired.
Controls
1. Via the copy meal servings combo box, you can copy another meal's set of servings into the meal you're currently modifying and update as desired.
Tips
1. A meal's descriptor is defaulted to a unique name of the form 'Meal @ date time' and may be changed to another, more descriptive, unique name.
2. As each serving (of a recipe that has defined nutrition) is added,
  1. A nutrition summary is displayed for the serving's portion. Change the portion, and you change the nutrition for that serving.
  2. The meal's nutrition summary at the top of the panel always reflects the total summed over the nutrition data of all assigned servings.
3. The meal and serving nutrition data columns are read-only. They can only be modified by specifying a serving's portion and / or selecting a recipe (that should have nutrition defined).

Nutrition Profile Panel

Purpose
1. Allows definition of nutrition data for a food type or product that is saved as a named profile and may be used as a source to compile nutrition data for recipes and meals.
Actions
1. Add at least one portion (or more with dissimilar units), with a unique descriptor, to define how much of a food type or product is required to achieve the specified nutrition values.
2. Add a nutrient entry and update the quantity for the default unit.
3. Copy the nutrient entries from another nutrition profile and update the quantities for the default unit.
Controls
Tips
1. The descriptor of a nutrition profile should be unique to be available and easily choosable at the nutrition construction panel when compiling nutrition data for a recipe.
2. You may copy the nutrient entries from multiple nutrition profiles as long as no nutrient is duplicated across any of those profiles. When a duplicate is detected, none of the nutrient entries for the offending profile are copied.

Recipe Panel

Purpose
1. Provides definition and management of a recipe. Doh!
Actions
1. The description tab supports definition and updates for the characteristics and classifications of the recipe.
2. The ingredients tab lists and supports definition and updates for recipe ingredients.
3. The directions tab supports definition and updates for instructions, modifications, and notes for the recipe.
4. Depress the recipe card button to peruse a summary of the recipe data you have saved.
5. Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your recipe.
Controls
1. Use the edit>conversion profile menu item to create a new or edit the recipe's currently-assigned conversion profile.
Tips
1. A recipe must have a least a title, one or more ingredients, and non-empty instructions to be saved. Otherwise, whaddya really got there, Abraham? Furthermore, the following rules apply:
  1. If the serving size unit is 'Serving', then the serving size quantity must be '1',
  2. If the yield and serving size units are incompatible, a conversion profile must be selected that defines how the conversion can be calculated between the units. A bit critical when constructed nutrition, defined for the recipe as a whole, has to be factored for meal portions and serving sizes.
2. The more tags you select in the Description > Classy section of the description tab, the more searchable the recipe is.
3. Within the ingredient textbox, one may specify a recipe as an ingredient via the following form: quantity recipe descriptor. Note the keyword, "recipe", must be used. Example: 0.5 recipe Mom's Flambéd Okra.
4. The custom combo box allows you to define unique tag values (I see Ritchie, and Jimmy, and Janis, ...) to categorize and search recipes in accordance with any misguided personal convention you may adhere to.
5. You can attribute your saved recipe to its source (e.g. originator's name, a business), or add any relevant reference link (as a URL) in the description tab reference section. A reference link can be launched directly from the tool for convenience given you already have the supporting application setup on your host (e.g. image viewer, web browser). Examples: http://www.example.com (for a web site) or file://C:/path/imageFilename (for an image on the host's file system). If you're not the attributing type: Bad dog, no biscuit!
6. For you ingenious types, you could cut and paste a whole slew of ingredient lines from your source material and paste the lot into the add textbox to have it auto-processed. You may still have to depress the add button for the last line (if it doesn't have a return character at the end).
7. Once an ingredient has been entered into the table, you can futz with its data in the table cells. This, since the Author does not yet have Skynet on contract to properly parse all human babble into its proper place in the universe. But soon. Very soon.
8. If a compound ingredient unit didn't properly parse, then perhaps the compound unit needs to be defined first via the keyword panel (or it was just poorly formed upon entry). Examples of proper form for entering compound units are:
  - 1 12 fluid ounce bottle vodka
  - 1 12 fl oz bottle rum
  - 1 bottle,12 fluid ounce whiskey
  - 1 bottle, 12 fl oz tequila
  - Are ya starting to see a pattern here?
  - In contrast, an example of a simple ingredient unit (i.e. not compound) is of the form:
    - 3 fluid ounces gin
9. Ingredients entered with the form, "1 egg", where the unit is also the name of the food, results in that name used for both the food and the unit in the ingredient table row. This is normal. Do not attempt to adjust the picture. We are in control.
10. If a recipe that's used in a serving's portion of a meal has its yield or nutrition data changed, the meal's nutrition data is also, automatically, updated. Be sure to use compatible unit names between the recipe's yield and any serving portions that reference the recipe; otherwise the serving's nutrition values all go to zero.
11. If there's a change in a recipe's yield or ingredient data (e.g. amount, edible, total count), the nutrition data previously constructed is very probably out-of-date and should be reconstructed to again be accurate for the recipe. This is decidedly a manual process that must be performed by the user to maintain accurate nutrition for that recipe. The meal logic will continue to use the nutrition data whether it's out-of-date or not.
12. After a recipe is saved, you can return to the main application panel (i.e. the CuttingBoard panel), select the recipe, and via either the menu item or the context menu option, construct and save nutrition for the recipe. You can replace a recipe's nutrition as many times as desired.

Summary Panels

This section describes those panels that are available to view summary data of an object that is managed by the application.

Recipe Card Panel

Purpose
1. Provides an, at-a-glance, read-only summary of the recipe.
Actions
1. The yield may be changed to linearly scale the ingredient amounts accordingly when you're lovingly envisioning a quadruple batch of brownies. If nutrition has been constructed, a summary is displayed that's also adjusted as a function of the recipe yield (so you get to see the caloric price of that batch of brownies).
Controls
1. Captain, the engines cannae take much more.
Tips
1. Not all things in this world scale linearly.
2. You can always add a link to an image of your creation (perhaps on your host's file system) that would be clickable via this panel.

Nutrition Facts Panel

Purpose
1. Provides a read-only view of the nutrition data (on a per serving basis) for the recipe. For each nutrient, both the absolute amount and the percent daily value are provided.
Actions
Controls
1. When incompatible units exist for the serving size and the recipe yield (the servings per recipe line), the amount displayed for serving size turns red to indicate that an unreliable guess was made with respect to how many servings are in the recipe. This is a warning that the nutrient amounts provided are probably wrong. To correct this condition, make sure a conversion profile is assigned to the recipe that defines the desired ratio between the two units to ensure an accurate calculation.
Tips
1. Numbers in the percent daily value column are based upon the DRI data as published by the US government. The applicable DRI data is selected per the user's default population segment (e.g. gender, age, activity level) as noted in the dietary reference panel. The user's default population segment is configurable via the preferences panel.
2. If you don't wish to see zero-valued data, select the recipe then the construct nutrition option to build and save a nutrition data set based upon the recipe ingredients.
3. The calories value displayed represents the sum of the Energy (KCAL) and Energy (Atwater Specific) entry values (from the nutrients section) as summed over all recipe ingredients per serving size based upon the assumption that the individual nutrient data source only supplies one or the other on a per food product (i.e. recipe ingredient) basis.

Nutrition Tally Panel

Purpose
1. Available from the calendar's week-day and month views, provides a read-only view of the nutrition data aggregated over several meals (possibly averaged over several days) on a per day basis. For each nutrient, both the absolute amount and the percent daily value (when it exists) are provided.
Actions
Controls
1. Context menu options applicable to one or more meal entries in the week-day and month views of the calendar are:
  1. View average nutrition for selected
    1. When used for a selection of more than one calendar entry on a single day produces an aggregated nutrition data of just those entries for that day.
    2. When used for a selection of an aggregate meal implies selection of all meals for that day.
    3. When used for a selection of more than one calendar entry across multiple days produces an aggregated nutrition data that is averaged across that number of days.
  2. View average nutrition for week
    1. When used for a selection of any one or more calendar entries produces aggregated nutrition data for that week's meals that is averaged by the number of days in the week (from Sunday through Saturday).
  3. View average nutrition for month
    1. When used for a selection of any one or more calendar entries produces aggregated nutrition data for that month's meals that is averaged by the number of days in that month.
2. The following warnings may be presented within the panel:
  1. At the top-left section of the panel, a red E may be presented when at least one included meal's serving is empty (i.e. has no recipe, or has an amount with a zero quantity or unit that is incompatible with the recipe's yield)
3. Numbers in the percent daily value column are based upon the DRI data as published by the US government. The applicable DRI data is selected per the user's default population segment (e.g. gender, age, activity level) as noted in the dietary reference panel. The user's default population segment is configurable via the preferences panel.
4. A question mark, "?", that precedes a nutrient's amount indicates an incomplete sum. That is, at least one of the included meal servings didn't have the nutrient defined in its nutrition data where that nutrient should be pertinent to any set of nutrition data. Only calories falls into this category at this time; the other nutrient's may simply not be present in a serving and so are not listed.
Tips
1. For the option, view average nutrition for selected:
  1. The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
  2. If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
2. For the option, view average nutrition for week:
  1. Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
3. For the option, view average nutrition for month:
  1. Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
4. For the incomplete sum warning:
  1. One may add the Energy (KCAL) nutrient with a value of "0" to the nutrition of a food or nutrition profile to suppress the warning.

Nutrition Definition Panels

This section describes those panels that are available to view and to define nutritional data for those applicable objects that are managed by the application.

Cooking Reference Panel

Purpose
1. Displays cooking reference data sourced from various government-sponsored agencies. Two types of information are available:
  - Yield factors are uniquely-defined per food, according to its initial state and the preparation and / or cooking methods applied, and represent a percentage change in yield (i.e. a loss or gain in mass) that occurs as a result of the treatment.
  - Retention factors are uniquely-defined per food, according to the cooking method applied, and represent a percentage change in retention (typically a loss) of a vitamin or mineral that occurs as a result of the treatment. Come-on now. Did ya really think that all of that bourbon just baked out of that cake before you gave it to little Billy?
Actions
1. When compiling nutrition via the nutrition construction panel (and only then), one may select (i.e. apply) any set of retention and yield factors to the set of chosen food products.
Controls
1. The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
Tips
1. Remember the garbage-in, garbage-out rule of computers. The application does not yet possess super-human, AI capabilities to ensure that your selections don't strand you in some misguided, calculation-falacy hell. Choose wisely.
2. Three of the most common cooking methods are: pan-fried (fat, water), cooked by dry heat (air, fat, radiation, conduction), cooked by moist heat (water, steam). Still reading then?

Dietary Reference Panel

Purpose
1. Displays dietary reference data sourced from the US government (as referenced from the source URL(s) at the bottom of the panel). Daily recommended intake levels (DRIs) of major food components (macro-nutrients), calories, minerals, vitamins, and select amino acids are displayed per population group within the respective nutrient group's tab. The daily values (DVs) shown may either be a Recommended Dietary Allowance (RDA), or, if the RDA is not established, an Adequate Intake (AI). If defined, Lower Limits (LLs) and Tolerable Upper Limits (ULs) are shown.
Actions
1. The data in the row identified as default (i.e. the user's population) is used by the application when calculating the daily value percentages that are presented in various nutrition views.
Controls
1. To delete a population group (and its daily values across all four tabs), select a row and depress the delete key. The application's original groups and the group currently labelled as the user's default (defined via the preferences panel) are not deleteable.
2. One can update any of the daily values by just re-importing the XML file with the desired values (unlike the other managed objects which require the original object to first be deleted from the application).
3. A nutrient's daily value data for a given population (and for a given weight for amino acids) is specified via the following formats, where DV represents a daily value that is either a RDA or an AI:

DV: Only the daily value is defined / available. The daily value is always green.
LL,DV,UL: All three numbers are defined.
LL-UL: Only a range of daily values, as defined by a lower and upper limit, is available (no single daily value is applicable).
>LL or <UL: Only one limit is available implying that a reasonable daily value is either greater than the lower limit or less than the upper limit.

Tips
1. The default population row is identified by the default tag in the population column of each tab.
2. Rather than accepting the application's default population, you should specify your group (Male, Female, ...), age, and physical activity level via the preferences panel to identify the population to which you belong.
3. You may update and import the dietary reference template XML file with one or more custom population groups and their corresponding dietary reference nutrient data values. The group value can be any name as long as it is unique WRT the other group values in the application.

Food Query Panel

Purpose
1. Used to obtain and apply nutrition data for a particular food (whether standalone or as a series of recipe ingredients). The nutrition data can be available via three options (the first two described are available via the source combo box selection):
  1. A product listing can be the result of a database query to an internet site (e.g. FDC) that allows the user to select the best fit per need,
  2. A list of NutritionProfile's, that allows the user to select from any pre-defined, locally-hosted nutrition data, or
  3. If the food has its own nutrition data defined, a use-nutrition button is displayed that allows the user to apply the food's default nutrition (in lieu of any listed item).
2. When either a food product from a list or the food's own nutrition is selected, that nutrition data is added to the nutrition construction panel.
3. Compiled / constructed nutrition values may be displayed for:
  1. A food in the food's edit panel,
  2. A recipe in the recipe's card panel or its nutritional facts panel,
  3. A meal and its servings in the meal's edit panel, and
  4. The calendar entries (both per meal and the per day meal aggregations).
Controls
1. The aggregate nutrition radio button option allows nutrition data for multiple food products to be aggregated within the nutrition construction panel resulting in per nutrient totals:
  1. When enabled, each selected food product's nutrition data is added as a separate column within the nutrition construction panel and summed into the total column (typically used in recipe-driven mode).
  2. When disabled, a general food may be queried for applicable food products. The selected product has its nutrition data added to the nutrition construction panel (with only a single column ever defined) and may be saved to that food for future nutrition calculations.
2. Depress the next button to cycle to the next ingredient of a recipe.
3. You may select from multiple sources of nutrition data:
  1. Two sources of nutrition data are selectable via the source combo box:
    - The default is the USDA's FDC web site, and the application uses HTTP requests to query the site's database for food products and for a food product's nutrition data.
      - For this source, you may limit the search to any combination of the following data types: Foundation, Survey (FNDDS), Branded, or SR Legacy. Use the aforementioned FDC site to look up the meaning of these FDC terms.
      - When food product result sets are large enough, the source may limit the number of products that it responds with to only those that best matched the queried food. If you desire a full set of results (which can be quite large and take longer to retrieve), enable the Show All Hits option (and pay attention to the in-progress bar).
      - Depress the query button to submit a lookup request to the FDC site for all food products that may be applicable for that food.
    - An alternate source is the collection of user-defined nutrition profiles which is not dependent upon any external source. These profiles are defined via the nutrition profile panel and saved in the application database when the desired nutrition data is not available from any other source.
  2. Recipes and foods may have their own custom nutrition data previously-defined and saved.
    - When compiling nutrition for a recipe and cycling through each ingredient, if that ingredient's' foodstuff already has nutrition defined, the use nutrition button will appear (independent of the nutrition source combo box selection) and may be used to apply that nutrition to the aggregate that is being compiled in the nutrition construction panel.
4. The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
5. Double-click on a food product to add its nutrition data into the nutrition construction panel (which is launched upon the first selection).
6. The ingredients-to-go status line indicates the number of ingredients that still require nutrition information from a selected food product and remains red until all are processed.
Tips
1. The food query panel can be launched in one of two modes:
  1. Free form: When no recipe has been selected before the food query panel is launched, you are free to query for anything you enter in the query text box.
  2. Recipe-driven: When a recipe has been selected on the main CuttingBoard panel before the food query panel is launched, the query text box is automatically pre-loaded with the food of each recipe ingredient (with any variety and / or attributes defined). Depress the next button to successively move on to the food of the recipe's next ingredient.
2. If the food products result is unfulfilling, you can modify any of the following and re-query to retrieve a new set of food products:
  1. the text in the query text box (add or remove characteristics of the food),
  2. change the "Require All Words" or "Require Exact Match" options.
3. Given the complexity of aggregating nutrition from each of a recipe's ingredients, the query button stays green until all ingredients have been processed to provide a cue that it is central to the process. Pick me ... pick me!
4. The retention column shows source-applied retention (i.e. the mixed or Y values) only for foods of the SR Legacy data type since only that data type has that information available via the food products response message used to populate this panel's data. For Survey (FNDDS) foods, indication of source-applied retention is only available when the specific food's nutrition data is retrieved via a food nutrition response message. The other data types specify no indication of source-applied retention.

Nutrition Construction Panel

Purpose
1. Provides display, management, and optionally aggregation, of nutrition data for one or more food products. The panel information is presented via two tables:
  1. The compiled nutrition table shows nutrient meta data on the leftmost portion and nutrient quantity (for the selected food or ingredient amounts) in the rightmost portion. The rightmost portion is further delineated into the following four aggregated columns (where the remaining columns each reflect the nutrition for a single food or ingredient):
    1. The total column displays the quantity of the nutrient summed across all foods/ingredients selected.
    2. The retention column shows the total quantity for the nutrient adjusted for those selected retention factors (if any) that are pertinent to the nutrient.
    3. The yield column shows the total quantity for the nutrient adjusted for those selected yield factors (if any) that are pertinent. The two nutrients, Energy (KCAL) and Energy (KJ), are recalculated according to the Energy Conversion Factors specified in ANNEX XIV of Regulation (EU) No. 1169/2011 (see the Data Sources reference below).
    4. The all-factored column shows the total quantity for the nutrient adjusted for those selected retention factors and yield factors (if any) that are pertinent. The Energy (KCAL) and Energy (KJ) nutrient values are carried over from the yield column.
  2. The factors table (at the panel's bottom) lists all active (i.e. selected) retention and yield factors that are applied for the food(s) or recipe ingredients. Their impact may be further limited to only those columns desired by editing the column assignment cell with the applicable column number(s).
Controls
1. The displayed amount (quantity and unit) used to calculate the displayed nutrition data for a selected food product may be changed (thus changing the displayed nutrition data). If changed when in recipe-driven mode and the result is saved, you must also explicitly update the recipe's ingredient amount to ensure the nutrition data matches the recipe. Yes Virginia, this could be automated.
2. A column may be deleted by selecting any cell in the column and depressing the delete key.
3. Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the nutrition data.
  1. When collecting nutrition data for a food (either from a food's pre-defined nutrition, one of the application's pre-defined nutrition profiles, or nutrition retrieved via the application's USDA FoodData Central interface), the data displayed in the food's column in the nutrition construction panel may have any of the following background colors to indicate accuracy of the data as a result of any unit conversion (e.g. 1/4 cup <=> 25 grams) required between the ingredient's portion and the sample portion of the food's nutrition. In order of decreasing accuracy:
    Grey (excellent accuracy)
    
    Either the units matched or any unit conversion was between completely compatible units.
    
    Yellow (good accuracy)
    
    FoodData Central can have portions (e.g. quantity not specified) that are used as a fallback and which still allow for valid results.
    
    Orange (ballpark accuracy)
    
    A straight-forward portion/unit conversion could not be performed, so an estimated, less accurate one was performed: 1 gram == 1 milliliter (which is only true for water). Is your food product mostly water?
    
    Red (game over, man!)
    
    You got goose eggs for data in that column. Either there's no way to convert the incompatible units (e.g. bolts to light-years) or the embedded machine intelligence is again sleeping on the job. To rectify, either:
    
    • choose the most applicable unit from those available in the combo box, or
    
    • delete the column and either pick another food product from the food query panel, or
    
    • select an applicable nutrition profile from the food query panel.
4. When the retrieved nutrition data of a food product's record has zero nutrients, a prior button is available that may be used to query the food product's previous record. This may be used to find a past record, possibly several versions back, that has nutrients specified.
5. At any time, the panel's unit (and/or quantity) may be changed to more closely align with your food / ingredient goal and the column's nutrition data will be updated per the new amount.
6. The unit conversion notification that pops-up to indicate a potential accuracy issue outlines a multi-option hint for handling the condition. This alert allows you to disable future conversion notifications (via a configuration preference) when you believe you've grasped the concept and become irritated by the repeated nagging. Thereafter, once the arrogance has faded, and your enfeebled mind no longer retains the fundamental cause of the pretty colors on the column headers, you can revisit the hint, reproduced here, so you may revel in these words of wisdom.
  If the converted data looks unreasonable:
  1) delete the food's nutrition column and try another food product from the Food Query Panel,
  2) change / save the unit of the recipe's ingredient to match one of the portion units available from the nutrition response,
  3) define an accurate conversion (via the food's keyword panel or the Conversion Profile Panel), to act as a bridge between the ingredient unit and at least one of the portion units available from the nutrition response,
  4) define a nutrition profile for the food and select it as a source at the Food Query Panel.
  A restart of the Food Query Panel is required for options 2 through 4.
7. Factor table utilization:
  1. When compiling nutrition, retention and / or yield factor application are only desirable when the selected food products don't already account for some intended series of preparation or cooking methods (e.g. baking a cake from raw ingredients). If you compile nutrition for a raw apple that you're going to eat as is ("you're going to wash that right?"), then there's no need to utilize a treatment factor to adjust the nutrient quantities.
  2. By default, all factors apply to all foods/ingredients in the compiled nutrition table. Only those nutrients in the compiled nutrition table that are listed in a retention factor's set of nutrients are adjusted (assuming a column assignment of "all").
  3. Any factor may be selected and deleted to remove its impact upon the final calculated nutrition; however, if a default yield factor exists for the recipe (i.e. a yield factor is displayed in the recipe's edit pane next to the yield control), it will automatically be reinserted in the factor table.
  4. To limit the a factor's impact to only a particular food/ingredient, edit the column assignment cell accordingly. For example, use "1,3" rather than "all" to only apply the factor to food/ingredient columns 1 and 3 (as identified at the top of the amount food amount column).
8. When the retention radio button is deselected, a simplier panel is presented by removing the yield and retention factor UI widgets. In this mode, the nutrition listed under the total column may be saved (yield and retention factors are disregared) and proves useful when no additional preparation or cooking methods need to be taken into account.
9. When the retention radio button is selected, the nutrition-column-to-save combo box may be used to specify which of the four columns should be saved as nutrition via the save-nutrition button. When the retention radio button is not selected, only the total column may be saved as nutrition.
Tips
1. Pay close attention to the amount (especially the unit) that is proposed for each recipe ingredient to ensure it's what you want. When the ingredient's unit is not available in the retrieved nutrition data set, the application attempts a best-effort guess to slavishly ingratiate itself to you. Machines can be so cloying.
2. Once nutrition is constructed for the recipe and saved, the data is viewable by accessing the recipe's nutrition facts panel. When retention is disabled, only the values in the total column may be saved as nutrition. When retention is enabled, either the total column values or the yield column values may be saved as nutrition per the nutrition-column-to-save combo box.
3. When saving to a food descriptor that is not already present in the database, choose a descriptor that is no more than three words long. Once nutrition is retrieved for a food and saved, the data is viewable by accessing the food's edit panel.
4. Limitation: the application currently only allows an existing recipe's nutrition data to be overwritten with a new set of nutrition data (modification of any given portion is not yet available).
5. When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
  1. Free form: the nutrition data displayed is applicable to (calculated from) the default portion of the selected food product or nutrition profile.
  2. Recipe-driven: the nutrition data displayed is applicable to (calculated from) the amount specified for the food of the recipe's ingredient.
6. You may delete a food product's nutrition column and choose another product from the food query panel for the corresponding ingredient.
7. You may adjust the portion amount to observe the change in nutrition data for any selected food product, but when it comes time to save the set of nutrition data for a recipe:
  1. A validity check is performed to ensure that each non-optional recipe ingredient has nutrition data for one and only one food product.
  2. For any column header with a grey background color: the portion data must match the ingredient portion (to assure overall nutritional accuracy for the recipe).
  3. For any column header with a yellow, orange, or red background color: the portion data may be changed for the food product to better approximate the recipe ingredient's portion. In this case, the validity check bypasses the portion check assuming that the user knows best. So choose wisely.
  4. The validity check will fail a save attempt for any column header with a red background color that has not had it's portion changed by the user.
8. A food product's nutrition column header will always retain it's original background color (event after a portion change) to remind you of the original state of the application's unit conversion accuracy.
9. If an FDC-supplied portion conversion can't be made, then:
  1. A conversion profile entry is used when defined (which can be brand-specific).
10. If you'd like to minimize the chance that you'll incur a conversion between an ingredient's unit and a selected food product's unit (a good thing):
  1. Make sure that ingredient units are a weight unit for dry edibles and a volume unit for liquids.
11. For only the SR Legacy or Survey (FNDDS)-sourced foods, an "R" after the ingredient index in the table column header indicates that the retrieved nutrient data for that food already has source-applied retention factors used in its derivation. Depending upon your use case, you may wish to consider whether any additional retention factor application is necessary given the desire for accuracy.

Viewer Panels

This section describes those panels that are available to view application operation or to browse internet sites.

Console Panel

Purpose
1. Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
Actions
1. The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection, the greater the number of traces produced (and the slower the application executes).
Controls
1. Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
2. Select and copy those traces that you wish to relay into, say, a support email.
Tips
1. To ease your journey through the storied history of application events past, log entry level severity is color-coded as follows (in order of severity): TRACE, DEBUG, INFO, WARN, ERROR. You do see the helpful hint here, no?
2. While the console's logs are updated immediately with the latest log events, those same events are buffered when it comes to writing them to the corresponding disk file. Use the tools > flush log menu item to flush any buffered log events to the log file on disk.

Conversion Calculator Panel

Purpose
1. Displays calculated conversions between units and attributes for a food that has a conversion profile.
Actions
1. Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
Controls
Tips
1. At least 20%, please.

Graph Panel

Purpose
1. Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
  1. The normal graph mode provides a top-down hierarchical structure of the application's managed object population allowing drill-down navigation to locate a desired object.
  2. The walkabout graph mode (g'day, mate) provides a connected, directed graph viewpoint of a managed object's linkage to other managed objects in the database (where some objects may be uninteresting, intermediate placeholders).
Actions
1. Go 'n' play. Are you not entertained?
2. When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
3. Connection labels are displayed only for the initial (normal-mode) CuttingBoard graph and for all walkabout graphs. For other (normal-mode) graphs, the labels tend to inhibit readability and so are suppressed (much like unwelcome memories of traumatic events). Arrow direction indicates how the link name should be applied between the two nodes.
4. The graph transitions to normal mode when:
  1. the graph panel is first launched,
  2. the home button is selected,
  3. the back/forward button transitions to a previous graph that was presented in normal mode, or
  4. a primary mouse button double-click is used on a node.
5. The graph transitions to walkabout mode when:
  1. a single-click of the mouse's secondary button is used on a node that represents a managed object, or
  2. the back/forward button transitions to a previous graph that was presented in walkabout mode.
Controls
1. The bottom of the graph panel shows the breadcrumb trail that brought you to the current root node and identifies where the back / forward buttons navigate to (if you dare select them).
2. Drag a node to a position more to your liking, if you require, but note well that a node will drag itself back to a place in this universe that it has an affinity for. You see, they're working things out.
3. Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
4. A node's appearence hints at its potential (much like a "come hither" look):
  1. a blue node represents a grouping node, and when it presents a thick boundary, is pregnant with children nodes:
    - a primary mouse button double-click to drill down into its data sprimary mouse button double-clickcases).
  2. a brown node represents a managed object that, in most cases, will respond to:
    - a primary mouse button double-click to enter its edit panel,
    - a secondary mouse button single-click to open its walkabout graph (showing its connections to other managed objects) or, in the case of a recipe, open its recipe card panel.
  3. a gold-with-redish-boundary node is the root node for that graph (i.e. point of origin for those easily confused WRT WTF is going on).
5. Drill down into a node's data set by double-clicking the primary mouse button.
6. Certain graph nodes (e.g. keyword and ingredient nodes in the CuttingBoard graph) are purposely only placeholders. Although they may show thick boundaries (indicating underlying populations), the display of these populations as a whole in a normal-mode graph are not permitted because, well, they can be fracking huge and non-helpful in a mind-numbing sort of fashion. Look, the Author is trying to protect you from the vastness of the universe (lookin' at you Cthulhu). They'll still pop-up in the walkabout graphs, but in a much more manageable quantity per graph.
Tips
1. Buy low, sell high. After all, it's not a profit if you don't sell.

Statistics Panel

Purpose
1. Provides application metrics (e.g. how many objects exist in the database).
Actions
1. Refresh the metrics after adding stuff if you're in that 'bored with it all' mood and would rather be playing Mahjong.
Controls
Tips
1. One unique nutrition summary exists for each meal and serving.

Web Panel

Purpose
1. Provides a minimal, in-application web browser
Actions
Controls
Tips
1. Do you really need any by this point, or have the machines not yet taken over in your neighborhood?

Application Panels

This section describes those panels that are available to view application metadata or to control application behavior.

About Panel

Purpose
1. Identifies some of the application's more prosaic information: version, author, support email, license.
Actions
1. Access the Author's web-site.
2. Launch an email to the support staff relaying praise, bewilderment, rage, bugs. But no trolling ... I have a delete key and I know how to use it.
3. Access the application license or the third-party package licenses.
Controls
Tips
1. Really? For an about panel?

Help Panel

Purpose
1. Provides mildly-helpful, somewhat-abusive documentation concerning the application's usage and function (or lack thereof).
Actions
Controls
Tips
1. For further help, see the Red Cross.

Preferences Panel

Purpose
1. It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
  1. The accepted preference values tab lists those preference values currently available to the application. Preference management is supported by two different points of view:
    - The initial preferences panel provides an operational view of what preference values are accepted and are either currently operational or will be operational after the application is restarted.
    - A second preferences panel provides a configuration view that allows the selection of new values for each of the preferences.
  2. The active property values tab lists those property values used by the application. The application obtains these values either from the host's environment variables or via the options specified on the application's command-line.
Actions
1. From the operational view:
  1. To launch the preference configuration panel, left-click the accepted preferences values tab, then the edit>preferences menu items,
  2. Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
2. From the configuration view:
  1. Enter a portion of a preference name or section in the search box to locate a desired preference,
  2. Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
  3. Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
Controls
Tips
1. Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
2. Before a change is accepted, a preference's value may undergo a validation check to ensure consistent application behavior (when dependencies exist among multiple preferences).
3. No color change hints are provided on this panel, so don't forget to depress the OK / APPLY buttons if you really wish to save your well-thought-out changes.
4. Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
  1. Relocate Active Artifact Directory: When chosen after a new location for the artifact directory is specified, the application will migrate the entire artifact directory content (including the database) to the new artifact directory upon application exit. The new path is automatically used when the application is next started.
  2. Remove Active Database On Exit: By performing this action, you will lose any custom data (e.g. keyword, recipe) that you've entered in the database unless you've exported said data to XML files at a safe location (which may then be imported into a new database). All non-database artifacts are moved and preserved. If the relocate artifact directory option is also chosen in conjunction with this remove database option, upon exit the application will move everything and then remove the database at the new location.
  3. If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
  4. The DisplayUnits and DisplayNumberRepresentation values are used as the defaults for recipe card amount scaling and representation (and may be overridden on a per recipe card basis). During recipe yield scaling, the native setting will retain the unit of the original amount, whereas, for the other two settings, the unit will morph into what's most appropriate in order to keep the quantity magnitude manageable.
  5. The CalendarRecurrence... set of preferences place an upper limit on the number of times that a meal may be scheduled to repeat for the given period. Setting these values too high can result in slow calendar processing. So none of this "to infinity and beyond" stuff, OK?
  6. The population segment preferences (i.e. Age, AgeUnit, Group, ActivityLevel) are used to identify your default daily recommended intake row (and calorie column) in the dietary reference panel and thus which daily values are used in the nutrition facts panel calculation for a recipe. The Weight, WeightUnit preferences are used to identify your daily recommended intake amounts for amino acids. Personalize for a custom fit!

Appendix

Terms

Definitions:

Classifier: A type of attribute tag that can be given to an Application Object (e.g. Cuisine for a recipe).
Descriptor: The name (or a very short descriptive phrase that acts like a name), of an object. Not to be confused with a description of a thing, which can go on, and on, ...
Portion: An amount of food composed of a quantity and a unit.

Abbreviations

AI - Adequate Intake
AMDR - Acceptable Macronutrient Distribution Range
DRI - Daily Recommended Intake
RDA - Recommended Dietary Allowance
USDA FDC - US Department of Agriculture's FoodData Central web site
XML - Extensible Markup Language

Frequently Asked Questions

Some random thoughts that may provide, for the impatient, insightful answers to those questions that the Author is darn tired of getting.

How are the daily value percentages calculated in the nutrition views?
1. - The daily value percentages shown in the various nutrition views indicate how much of a nutrient's RDA or AI, as displayed in the Dietary Reference panel, is available in the editable (e.g. food, recipe, meal) given its portion.
  - Note that the general population (i.e. the one-size-fits-all) RDA / AI values that are used for typical food product nutrition fact labels are not used by this application. Rather, in an attempt to provide data that is better customized to the user, the application uses the user-selected population group (and weight) to select those specific values as published in the documents referenced at the bottom of the Dietary Reference panel and also listed in the Data Sources section of this online help. The general population values, in contrast, are noted in the document Food Labeling: Revision of the Nutrition and Supplement Facts Labels: Guidance for Industry Small Entity Compliance Guide which is produced by the Office of Nutrition and Food Labeling in the Center for Food Safety and Applied Nutrition at the USDA FDA.
  - While some of the nutrition views loosely follow the structure of the FDA's label guidance to provide information in a familiar guise, no claims of format or content adherence are made.
What voodoo must I invoke to achieve selection of table item(s)?
1. - To select multiple items: shift + primary-mouse-button-click
  - To deselect an item: ctrl + primary-mouse-button-click

Infrastructure

Open Source Components

This product was built using, and includes software developed by, multiple, independent open source projects as noted below. Thanks, all. Really.
Mark well (as noted below) that all third-party code libraries utilized are covered under their own licenses and that the CuttingBoard application code is covered under its own, separate license (and copyright).

Incorporated Open Source Components
Component	Version	Role	License	Comment
CuttingBoard	Latest	Runtime	GPL-3.0	The tortured, entangled bits that are the soul of the CuttingBoard application
OpenJDK	22	Runtime	GPL-2.0+CE	Java Development Kit.
OpenJFX	24-ea+5	Runtime	GPL-2.0	Java client application graphics platform.
Ferma	3.3.2	Runtime	Apache 2.0	An ORM / OGM for the TinkerPop graph stack.
TinkerPop	3.5.1	Runtime	Apache 2.0	A graph computing framework for graph databases and graph analytic systems.
JanusGraph	1.1.0-20240829-135020.8bbac7f	Runtime	Apache 2.0	A graph database.
Gremlin	3.7.2	Runtime	Apache 2.0	Gremlin is the graph traversal language of Apache TinkerPop.
Lucene	8.9.0	Runtime	Apache 2.0	Library providing indexing and search features.
Oracle NoSQL DB Server	5.18.3.12	Runtime	Apache 2.0	Berkeley Database Java Edition - build and runtime support.
Apache Commons Lang3	3.17.0	Runtime	Apache 2.0	Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
Apache Commons Text	1.11.0	Runtime	Apache 2.0	Library focused on algorithms working on strings.
Apache Commons Math	3.6.1	Runtime	Apache 2.0	Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
Apache Commons IO	2.15.1	Runtime	Apache 2.0	Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
Apache HttpClient5	5.3.1	Runtime	Apache 2.0	HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
Apache HttpAsyncClient	4.1.5	Runtime	Apache 2.0	Library implementing the client side of the latest HTTP standards and recommendations for an application based upon an asynchronous, event driven I/O model.
Apache HttpClient Mime	4.5.14	Runtime	Apache 2.0	HttpComponents HttpClient - MIME coded entities.
Apache HttpCore NIO	4.4.16	Runtime	Apache 2.0	HttpComponents Core (non-blocking I/O).
JSON In Java	20240303	Runtime	JSON	A reference implementation of a JSON package in Java.
Jackson Databind	2.17.0	Runtime	Apache 2.0	General data-binding functionality for Jackson: works on core streaming API.
Unirest Java	4.4.4	Runtime	MIT	Simplified, lightweight HTTP client library.
Dorkbox Version	3.1	Runtime	MIT	Java Semantic Versioning, relaxed.
Apache Log4j API	2.23.1	Runtime	Apache 2.0	Library containing Java-based logging utilities.
Apache PDFBox	2.0.27	Runtime	Apache 2.0	Library providing utilities to create, manipulate, and extract content from PDF documents.
Pdfbox2 Layout	1.0.1	Runtime	MIT	Library providing PDF text layout utilities.
Version	2.4	Runtime	MIT	Java library for semantic versioning.
JScience	4.3.1	Runtime	Apache 2.0	Java library for the scientific community: units of measurement.
CalendarFX	11.12.7	Runtime	Apache 2.0	Java framework for creating calendar views.
CalendarFXRecurrence	11.6.4	Runtime	Apache 2.0	Java framework for creating calendar views (contains the RFC 2445 support).
PreferencesFX	11.17.0	Runtime	Apache 2.0	Java framework for creating a UI for application settings / preferences.
RichTextFX	0.11.2	Runtime	BSD 2-Clause "Simplified" License	Rich-text area for JavaFX.
JavaFXSmartGraph	0.9.4	Runtime	MIT	Directed-graph visualization for JavaFX.
ControlsFX	11.2.1	Runtime	BSD 3-Clause "New" or "Revised" License	UI controls for JavaFX.
Schema-org-java	0.6.0	Runtime	Apache 2.0	Commons and serializer libraries and maven plugin generator for Schema.org types.
FOKProjects MSLinks	1.0.6.2	Runtime	Apache 2.0	Java library for parsing and creating Windows shortcut files.
kordamp.ikonli	12.3.1	Runtime	Apache 2.0	Icon packs for Java applications.
Cutting Board Icon		Runtime	Creative Common Attribution 3.0	Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
Inflector		Runtime	Eclipse Public License version 1.0	File containing language utilities.
ICU4J	75.1	Runtime	Unicode® Copyright	Set of Java libraries providing Unicode and Globalization support.
FoodData Central API	1.0.0	REST API	Creative Commons 0 1.0 Universal	USDA web server API that provides query and extraction capability for food product nutrition.
Eclipse IDE	2022-09 (4.25.0)	Build	Apache 2.0	Integrated Development Environment for Java Developers.
JUnit Jupiter API/Engine	5.11.0	Build	EPL 2.0	Testing framework for Java.
Maven	POM version 4.0.0	Build	Apache 2.0	Software project management and comprehension tool.
SceneBuilder	18	Build	BSD license, via Gluon	Drag and drop user interface design tool.

Data Sources

Mark well that all third-party data sources that are utilized are covered under their own licenses as noted in the citations below.

Incorporated Data Sources
Data Source	Identification	Copyright	Citation
USDA FoodData Central Composition Data	April 2023	Public Domain (not copyrighted)	U.S. Department of Agriculture, Agricultural Research Service. FoodData Central, 2020. fdc.nal.usda.gov
Nutrient Recommendations: Daily Values	-	-	U.S. Office of Dietary Supplements, National Institutes of Health
Nutrient Recommendations: Dietary Reference Intakes	-	-	U.S. Office of Dietary Supplements, National Institutes of Health
Dietary Guidelines for Americans, 2020-2025, Appendix 2	ISBN: 9780160955990	-	U.S. Department of Agriculture and U.S. Department of Health and Human Services. Dietary Guidelines for Americans, 2020-2025. 9th Edition. December 2020. Available at DietaryGuidelines.gov
Dietary Reference Intakes: The Essential Guide to Nutrient Requirements	DOI 10.17226/11537	National Academy of Sciences	Institute of Medicine 2006. Dietary Reference Intakes: The Essential Guide to Nutrient Requirements. Washington, DC: The National Academies Press. https://doi.org/10.17226/11537
Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids	DOI 10.17226/10490	National Academy of Sciences	Institute of Medicine 2005. Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids. Washington, DC: The National Academies Press. https://doi.org/10.17226/10490
Food Labeling Revision of the Nutrition and Supplement Facts Labels (p. 905)	FR Doc. 2016-11867 Filed: 5/20/2016 8:45 am; Publication Date: 5/27/2016	-	U.S. Food and Drug Administration, Health and Human Services
Tables on weight yield of food and retention factors of food constituents for the calculation of nutrient composition of cooked foods (dishes)	A. Bognár; ISSN 0933 - 5463; Berichte der Bundesforschungsanstalt für Ernährung (BFE); 2002	-	Federal Nutrition Research Centre, Germany
USDA ARS Agriculture Handbook No. 102: Food Yields Summarized by Different Stages of Preparation	Matthews and Garrison; September 1975	-	U.S. Department of Agriculture; Agricultural Research Service
USDA Table of Cooking Yields for Meat and Poultry	Roseland, et al.; Release 2; September 2014	-	U.S. Department of Agriculture; Agricultural Research Service; Beltsville Human Nutrition Research Center; Nutrient Data Laboratory
Report on Nutrient Losses and Gains Factors used in European Food Composition Databases	Federal Research Centre for Nutrition and Food (BfEL), Karlsruhe, Germany; April 2006	-	European Food Information Resource Network (EuroFIR)
REGULATION (EU) No 1169/2011 OF THE EUROPEAN PARLIAMENT AND OF THE COUNCIL of 25 October 2011 on the provision of food information to consumers	Official Journal of the European Union, L304, 22.11.2011, p. 18	-	European Union
USDA Table of Nutrient Retention Factors	USDA Table of Nutrient Retention Factors, Release 6, Dec 2007	-	U.S. Department of Agriculture; Agricultural Research Service; Beltsville Human Nutrition Research Center; Nutrient Data Laboratory
The Composition of Foods	Sixth summary edition. Cambridge: Royal Society of Chemistry. Food Standards Agency, UK, 2004	-	Public Health England: contains public sector information licensed under the Open Government License v3.0
Schema.org Recipe type (and all supporting types)	Version 27.02, without change	CC BY-SA 3.0	About Schema.org

User's Manual

The CuttingBoard Application

Theory

Concepts

Architecture

Usability

Behavior

XML Importation

Retention and Yield Factors

Updates

Database Regeneration

Manual

Automatic

Communication

Internet

Configuration

Beware. Here Be Dragons

Nuts and Bolts

Application Widgets

Internal Objects

External Artifacts

Directories

Configuration Files

Media Types

Database

Command-line Invocation

Application Panels

General Tips

Collection Panels

CuttingBoard Panel

Calendar Panel

Foods Panel

Substitutes Panel

Tags Panel

Tree Panel

Meals Panel

Profiles Panel

Quotes Panel

Editor Panels

Conversion Profile Panel

Keyword Panel

Meal Panel

Nutrition Profile Panel

Recipe Panel

Summary Panels

Recipe Card Panel

Nutrition Facts Panel

Nutrition Tally Panel

Nutrition Definition Panels

Cooking Reference Panel

Dietary Reference Panel

Food Query Panel

Nutrition Construction Panel

Viewer Panels

Console Panel

Conversion Calculator Panel

Graph Panel

Statistics Panel

Web Panel

Application Panels

About Panel

Help Panel

Preferences Panel

Appendix

Terms

Abbreviations

Frequently Asked Questions

Infrastructure

Open Source Components

Data Sources

Navigation menu

Search