Entangled Bits - User contributions [en]

User's Manual

2026-08-18T14:41:40Z

Admin: With all the Fixin's (v0.48.5)

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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.
# The application has multiple actions that may be performed upon its data.
#* The save operation is used to persist data within the application's database or preferences file.
#* The print operation is used to transmit application data to a printer (as PDF).
#* The export operation is used to save application data to a file (as PDF or XML).
# Formats currently supported for application data.
#* [['#PDF'|PDF]]-based files are used to export application data. For quick access, paste your favorite recipes on your refridgerator or affix them to your children's foreheads.
### You can output your data to PDF files or the printer to gift.
### If an export operation (save or print) fails because the configured font doesn't support the more esoteric Unicode characters (e.g. the embedded Helvetica font), switch to one of the system-supplied fonts (NotoSan, LiberationSans) via the preferences panel (offered only when available on the host). This may occur when ''recipe'' data originates via a website scrape.
#* [['#XML'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
### You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
### 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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.

===== Initiation =====

If one wishes to upgrade an existing installation (e.g. zip and certain deb installations) to a new version (that may include 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.
#As a backup precaution, you may wish to manually perform a tools > export all operation to a safe, backup directory on your host machine.
#Check for an available update via help > Check for update.
#Select "yes" at the Proceed with update? alert panel.
#After the download and bundle extraction has completed, the application will automatically export all of the its data into its export directory as XML files whose names are tagged with the current version. Please wait for this to finish.
#Exit the application.
#Restart the application and patiently wait for the database to be recreated. Once the database has been recreated, the tagged, exported XML files (from the previous step) will automatically be imported to restore any of your custom / additional data that was not part of the original application package. Please wait for this step to finish.
#If there's ever any need to manually import any highly-cherished, previously-exported XML files (i.e. those from the first step, the backup precaution step, if you get where I'm going with this), use the tools > import operation to repopulate the database (for each file in the following ordered sequence). One may also use the tools > import all operation which automates this effort. 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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##ConversionProfile
##NutritionProfile
##Food
##Note
##Quote
##Recipe
##Meal

===== Automation =====

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.</li>
#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'|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. The application anonymously informs the home site concerning the disposition of the update's download (controllable via the LogToServer preference).
# 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.

=== Quick Start ===

# The application can be deployed to a personal computer via a Windows installation bundle (i.e. a *.msi file), a Debian installation bundle (i.e. a *.deb file for Debian-based Linux hosts), or via a compressed zip file (runnable on any host that supports Java, fingers crossed). All contain the fileset required to run the application: a jar, launch scripts, any control files, and a README. The README_START_CuttingBoard.txt file contains hints that might resolve some of the typical gotchas.

=== 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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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).
#; LogToServer
#: Enables minimal, anonymous, application-to-server, metric logging (as feedback for devOps to gauge application efficacy).
#; 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%20FDC'|USDA FDC API KEY]] that is used to uniquely identify the user of the FDC service,
#; FdcUrl
#: Specifies the FoodData Central internet server from which food product and nutrition 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.
#; OutputAllData
#: Specifies whether all object data (vs. a minimal subset) is output during PDF generation.
#; OutputDefaultFormat
#: Specifies the default document format to be presented for an export operation (alternatives may be subsequently chosen).
#; OutputPerPage
#: Specifies whether each object starts on a new page during PDF generation into a single document.
#; OutputFileSelection
#: Specifies whether the file chooser prompt (for location and filename) is enabled.
#; OutputFont
#: Specifies the font that is used for PDF document generation.
#; OutputConsolidatedPdfFile
#: Specifies whether all objects are consolidated into a single document during PDF generation (vs. each to a separate document).
#; OutputConsolidatedXmlFile
#: Specifies whether all objects are consolidated into a single document during XML generation (vs. each to a separate document).
#; 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.

{| class="wikitable"
|+ 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 || y || y || y || y
|-
|DietaryReference || 2 || n || y || y || n
|-
|Foods || 2 || y || y || y || y
|-
|FoodUnits || 2 || n || y || y || n
|-
|LanguageReference || 2 || n || y || y || n
|-
|Meals || 2,3 || y || y || y || y
|-
|Notes || 2 || n || y || y || n
|-
|NutrientReference || 2 || n || y || y || n
|-
|Nutrients || 2 || n || y || y || n
|-
|NutritionProfiles || 2 || y || y || y || y
|-
|Quotes || 2 || n || y || y || n ||
|-
|Recipes || 2,3 || y || y || y || y
|-
|RetentionFactors || 2 || n || y || y || n
|-
|Substitutes || 2 || y || y || y || y
|-
|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 and the OutputSinglePdfFile and OutputPerPage options are enabled.


===== 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html Configuration] in accordance with its own product documentation.


=== Command-line Invocation ===

# Command-line invocation may be of the forms: java -jar cuttingboard.jar java -Dorg.entangledbits.cuttingboard.preferencesFile=preferences.xml -jar cuttingboard.jar >>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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## The application state appears in the control bar at the top of the panel to indicate the current processing state of lengthy operations.
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## Just as one may export or import a particular set of managed objects via a given XML file, the tools > export all and tools > import all options may be used to automatically export or import all application-managed objects via the complete set of XML files (and in the proper sequence). The import all action prompts for selection of a directory that contains all of the required files.
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per recipe nutrient amount matches or exceeds the desired nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
### Via the context menu of a ''note'' you can view or copy the whole table's content.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is. All the ''tag'' combo boxes in this section are searchable (one may enter filtering text to limit what's shown) and multi-selection (one may check multiple items per each combo box).
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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.
## Hover the mouse over column headers to view tool tips and information pertinent for that column.
## ''Yield factors'' and ''retention factors'' may be applied to modify the values in their respective columns in accordance with how the ''recipe'' and its ''ingredients'' are prepared / cooked.
### Greyed-out table cell text indicates that the values may be ambiguous (i.e. sketchy, inaccurate, or just not applicable).
### Column values are greyed-out when supporting factors are not applied (as observed in the factor table at the bottom of the panel).
### When both factor types are not present, only the total column is interesting and typically represents values for an unprepared / raw scenario (i.e. the selected ''food'' products, unchanged).
### The retention, yield, and all-factors cells in the Atwater General / Specific Factors nutrient rows are always greyed-out since they currently only reflect their total values irrespective of any applied ''yield factors'' or ''retention factors'' (i.e. further implementation work required).
### The energy (both as KCAL and KJ) nutrient rows:
#### Are always made available irrespective of whether a ''retention factor'' is applied or when only AGF/ASF energy nutrient rows are available for the selected ''food'' products.
#### The all-factors cells display the total energy of all ''food'' products selected for the ''recipe ingredients'' as calculated using protein, fat, carbohydrate, fiber, alcohol, and organicAcid values. Their yield and retention cell values are always greyed-out.


=== Viewer Panels ===

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


==== Console Panel ====

# Purpose
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### The active system properties 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted application preferences tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 ===

* AGF - [https://fdc.nal.usda.gov/Foundation_Foods_Documentation Atwater General Factor]
* AI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* ASF - [https://fdc.nal.usda.gov/Foundation_Foods_Documentation Atwater Specific Factor]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* KCAL - [https://en.wikipedia.org/wiki/Calorie KiloCalorie (the amount of energy needed to raise the temperature of 1 kg of water by 1 celcius degree (1°C))]
* KJ - [https://en.wikipedia.org/wiki/Joule' KiloJoule]
* PDF - [https://en.wikipedia.org/wiki/PDF Portable Data Format]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [https://jsoup.org/ jsoup] || Runtime || [https://github.com/jhy/jsoup/blob/master/LICENSE MIT] || HTML parser, built for HTML editing, cleaning, scraping, and XSS safety.
|-
| [http://unirest.io/ Unirest Java] || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/vandeseer/easytable easytable] || Runtime || MIT || Library providing PDF table layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/DmitriiShamrikov/mslinks MSLinks] || Runtime || [https://github.com/DmitriiShamrikov/mslinks?tab=WTFPL-1-ov-file WTFPL] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2026-02-14T00:27:35Z

Admin: Protected "User's Manual" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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.
# The application has multiple actions that may be performed upon its data.
#* The save operation is used to persist data within the application's database or preferences file.
#* The print operation is used to transmit application data to a printer (as PDF).
#* The export operation is used to save application data to a file (as PDF or XML).
# Formats currently supported for application data.
#* [['#PDF'|PDF]]-based files are used to export application data. For quick access, paste your favorite recipes on your refridgerator or affix them to your children's foreheads.
### You can output your data to PDF files or the printer to gift.
### If an export operation (save or print) fails because the configured font doesn't support the more esoteric Unicode characters (e.g. the embedded Helvetica font), switch to one of the system-supplied fonts (NotoSan, LiberationSans) via the preferences panel (offered only when available on the host). This may occur when ''recipe'' data originates via a website scrape.
#* [['#XML'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
### You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
### 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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. The application anonymously informs the home site concerning the disposition of the update's download (controllable via the LogToServer preference).
# 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.

=== Quick Start ===

# The application can be deployed to a personal computer via a windows installation executable (i.e. a *.msi file) or via a compressed zip file. Both contain the same fileset: a jar, launch scripts, and a README. The README_START_CuttingBoard.txt file contains hints that might resolve some of the typical gotchas.

=== 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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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).
#; LogToServer
#: Enables minimal, anonymous, application-to-server, metric logging (as feedback for devOps to gauge application efficacy).
#; 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%20FDC'|USDA FDC API KEY]] that is used to uniquely identify the user of the FDC service,
#; FdcUrl
#: Specifies the FoodData Central internet server from which food product and nutrition 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.
#; OutputAllData
#: Specifies whether all object data (vs. a minimal subset) is output during PDF generation.
#; OutputDefaultFormat
#: Specifies the default document format to be presented for an export operation (alternatives may be subsequently chosen).
#; OutputPerPage
#: Specifies whether each object starts on a new page during PDF generation into a single document.
#; OutputFileSelection
#: Specifies whether the file chooser prompt (for location and filename) is enabled.
#; OutputFont
#: Specifies the font that is used for PDF document generation.
#; OutputConsolidatedPdfFile
#: Specifies whether all objects are consolidated into a single document during PDF generation (vs. each to a separate document).
#; OutputConsolidatedXmlFile
#: Specifies whether all objects are consolidated into a single document during XML generation (vs. each to a separate document).
#; 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.

{| class="wikitable"
|+ 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 || y || y || y || y
|-
|DietaryReference || 2 || n || y || y || n
|-
|Foods || 2 || y || y || y || y
|-
|FoodUnits || 2 || n || y || y || n
|-
|LanguageReference || 2 || n || y || y || n
|-
|Meals || 2,3 || y || y || y || y
|-
|Notes || 2 || n || y || y || n
|-
|NutrientReference || 2 || n || y || y || n
|-
|Nutrients || 2 || n || y || y || n
|-
|NutritionProfiles || 2 || y || y || y || y
|-
|Quotes || 2 || n || y || y || n ||
|-
|Recipes || 2,3 || y || y || y || y
|-
|RetentionFactors || 2 || n || y || y || n
|-
|Substitutes || 2 || y || y || y || y
|-
|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 and the OutputSinglePdfFile and OutputPerPage options are enabled.


===== 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per recipe nutrient amount matches or exceeds the desired nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
### Via the context menu of a ''note'' you can view or copy the whole table's content.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is. All the ''tag'' combo boxes in this section are searchable (one may enter filtering text to limit what's shown) and multi-selection (one may check multiple items per each combo box).
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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.
## Hover the mouse over column headers to view tool tips and information pertinent for that column.
## ''Yield factors'' and ''retention factors'' may be applied to modify the values in their respective columns in accordance with how the ''recipe'' and its ''ingredients'' are prepared / cooked.
### Greyed-out table cell text indicates that the values may be ambiguous (i.e. sketchy, inaccurate, or just not applicable).
### Column values are greyed-out when supporting factors are not applied (as observed in the factor table at the bottom of the panel).
### When both factor types are not present, only the total column is interesting and typically represents values for an unprepared / raw scenario (i.e. the selected ''food'' products, unchanged).
### The retention, yield, and all-factors cells in the Atwater General / Specific Factors nutrient rows are always greyed-out since they currently only reflect their total values irrespective of any applied ''yield factors'' or ''retention factors'' (i.e. further implementation work required).
### The energy (both as KCAL and KJ) nutrient rows:
#### Are always made available irrespective of whether a ''retention factor'' is applied or when only AGF/ASF energy nutrient rows are available for the selected ''food'' products.
#### The all-factors cells display the total energy of all ''food'' products selected for the ''recipe ingredients'' as calculated using protein, fat, carbohydrate, fiber, alcohol, and organicAcid values. Their yield and retention cell values are always greyed-out.


=== Viewer Panels ===

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


==== Console Panel ====

# Purpose
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### The active system properties 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted application preferences tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 ===

* AGF - [https://fdc.nal.usda.gov/Foundation_Foods_Documentation Atwater General Factor]
* AI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* ASF - [https://fdc.nal.usda.gov/Foundation_Foods_Documentation Atwater Specific Factor]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* KCAL - [https://en.wikipedia.org/wiki/Calorie KiloCalorie (the amount of energy needed to raise the temperature of 1 kg of water by 1 celcius degree (1°C))]
* KJ - [https://en.wikipedia.org/wiki/Joule' KiloJoule]
* PDF - [https://en.wikipedia.org/wiki/PDF Portable Data Format]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 23 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 25.0.2 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.2.0-20251114-142114.b424a8f || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.20.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.15.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.21.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.6 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20251224 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.21.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [https://jsoup.org/ jsoup] || 1.22.1 || Runtime || [https://github.com/jhy/jsoup/blob/master/LICENSE MIT] || HTML parser, built for HTML editing, cleaning, scraping, and XSS safety.
|-
| [http://unirest.io/ Unirest Java] || 4.7.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.2 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.25.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 3.0.6 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/vandeseer/easytable easytable] || 1.0.2 || Runtime || MIT || Library providing PDF table layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 12.0.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.5 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.3 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.9.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/DmitriiShamrikov/mslinks MSLinks] || 1.1.0 || Runtime || [https://github.com/DmitriiShamrikov/mslinks?tab=WTFPL-1-ov-file WTFPL] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.4.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 78.2 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 6.0.1 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2026-02-14T00:27:14Z

Admin: Framework release with bug fixes (v0.48.3)

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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.
# The application has multiple actions that may be performed upon its data.
#* The save operation is used to persist data within the application's database or preferences file.
#* The print operation is used to transmit application data to a printer (as PDF).
#* The export operation is used to save application data to a file (as PDF or XML).
# Formats currently supported for application data.
#* [['#PDF'|PDF]]-based files are used to export application data. For quick access, paste your favorite recipes on your refridgerator or affix them to your children's foreheads.
### You can output your data to PDF files or the printer to gift.
### If an export operation (save or print) fails because the configured font doesn't support the more esoteric Unicode characters (e.g. the embedded Helvetica font), switch to one of the system-supplied fonts (NotoSan, LiberationSans) via the preferences panel (offered only when available on the host). This may occur when ''recipe'' data originates via a website scrape.
#* [['#XML'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
### You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
### 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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. The application anonymously informs the home site concerning the disposition of the update's download (controllable via the LogToServer preference).
# 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.

=== Quick Start ===

# The application can be deployed to a personal computer via a windows installation executable (i.e. a *.msi file) or via a compressed zip file. Both contain the same fileset: a jar, launch scripts, and a README. The README_START_CuttingBoard.txt file contains hints that might resolve some of the typical gotchas.

=== 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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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).
#; LogToServer
#: Enables minimal, anonymous, application-to-server, metric logging (as feedback for devOps to gauge application efficacy).
#; 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%20FDC'|USDA FDC API KEY]] that is used to uniquely identify the user of the FDC service,
#; FdcUrl
#: Specifies the FoodData Central internet server from which food product and nutrition 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.
#; OutputAllData
#: Specifies whether all object data (vs. a minimal subset) is output during PDF generation.
#; OutputDefaultFormat
#: Specifies the default document format to be presented for an export operation (alternatives may be subsequently chosen).
#; OutputPerPage
#: Specifies whether each object starts on a new page during PDF generation into a single document.
#; OutputFileSelection
#: Specifies whether the file chooser prompt (for location and filename) is enabled.
#; OutputFont
#: Specifies the font that is used for PDF document generation.
#; OutputConsolidatedPdfFile
#: Specifies whether all objects are consolidated into a single document during PDF generation (vs. each to a separate document).
#; OutputConsolidatedXmlFile
#: Specifies whether all objects are consolidated into a single document during XML generation (vs. each to a separate document).
#; 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.

{| class="wikitable"
|+ 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 || y || y || y || y
|-
|DietaryReference || 2 || n || y || y || n
|-
|Foods || 2 || y || y || y || y
|-
|FoodUnits || 2 || n || y || y || n
|-
|LanguageReference || 2 || n || y || y || n
|-
|Meals || 2,3 || y || y || y || y
|-
|Notes || 2 || n || y || y || n
|-
|NutrientReference || 2 || n || y || y || n
|-
|Nutrients || 2 || n || y || y || n
|-
|NutritionProfiles || 2 || y || y || y || y
|-
|Quotes || 2 || n || y || y || n ||
|-
|Recipes || 2,3 || y || y || y || y
|-
|RetentionFactors || 2 || n || y || y || n
|-
|Substitutes || 2 || y || y || y || y
|-
|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 and the OutputSinglePdfFile and OutputPerPage options are enabled.


===== 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per recipe nutrient amount matches or exceeds the desired nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
### Via the context menu of a ''note'' you can view or copy the whole table's content.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is. All the ''tag'' combo boxes in this section are searchable (one may enter filtering text to limit what's shown) and multi-selection (one may check multiple items per each combo box).
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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.
## Hover the mouse over column headers to view tool tips and information pertinent for that column.
## ''Yield factors'' and ''retention factors'' may be applied to modify the values in their respective columns in accordance with how the ''recipe'' and its ''ingredients'' are prepared / cooked.
### Greyed-out table cell text indicates that the values may be ambiguous (i.e. sketchy, inaccurate, or just not applicable).
### Column values are greyed-out when supporting factors are not applied (as observed in the factor table at the bottom of the panel).
### When both factor types are not present, only the total column is interesting and typically represents values for an unprepared / raw scenario (i.e. the selected ''food'' products, unchanged).
### The retention, yield, and all-factors cells in the Atwater General / Specific Factors nutrient rows are always greyed-out since they currently only reflect their total values irrespective of any applied ''yield factors'' or ''retention factors'' (i.e. further implementation work required).
### The energy (both as KCAL and KJ) nutrient rows:
#### Are always made available irrespective of whether a ''retention factor'' is applied or when only AGF/ASF energy nutrient rows are available for the selected ''food'' products.
#### The all-factors cells display the total energy of all ''food'' products selected for the ''recipe ingredients'' as calculated using protein, fat, carbohydrate, fiber, alcohol, and organicAcid values. Their yield and retention cell values are always greyed-out.


=== Viewer Panels ===

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


==== Console Panel ====

# Purpose
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### The active system properties 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted application preferences tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 ===

* AGF - [https://fdc.nal.usda.gov/Foundation_Foods_Documentation Atwater General Factor]
* AI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* ASF - [https://fdc.nal.usda.gov/Foundation_Foods_Documentation Atwater Specific Factor]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* KCAL - [https://en.wikipedia.org/wiki/Calorie KiloCalorie (the amount of energy needed to raise the temperature of 1 kg of water by 1 celcius degree (1°C))]
* KJ - [https://en.wikipedia.org/wiki/Joule' KiloJoule]
* PDF - [https://en.wikipedia.org/wiki/PDF Portable Data Format]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 23 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 25.0.2 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.2.0-20251114-142114.b424a8f || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.20.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.15.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.21.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.6 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20251224 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.21.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [https://jsoup.org/ jsoup] || 1.22.1 || Runtime || [https://github.com/jhy/jsoup/blob/master/LICENSE MIT] || HTML parser, built for HTML editing, cleaning, scraping, and XSS safety.
|-
| [http://unirest.io/ Unirest Java] || 4.7.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.2 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.25.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 3.0.6 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/vandeseer/easytable easytable] || 1.0.2 || Runtime || MIT || Library providing PDF table layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 12.0.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.5 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.3 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.9.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/DmitriiShamrikov/mslinks MSLinks] || 1.1.0 || Runtime || [https://github.com/DmitriiShamrikov/mslinks?tab=WTFPL-1-ov-file WTFPL] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.4.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 78.2 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 6.0.1 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2026-02-14T00:21:31Z

Admin: Removed protection from "User's Manual"

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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.
# The application has multiple actions that may be performed upon its data.
#* The save operation is used to persist data within the application's database or preferences file.
#* The print operation is used to transmit application data to a printer (as PDF).
#* The export operation is used to save application data to a file (as PDF or XML).
# Formats currently supported for application data.
#* [['#PDF'|PDF]]-based files are used to export application data. For quick access, paste your favorite recipes on your refridgerator or affix them to your children's foreheads.
### You can output your data to PDF files or the printer to gift.
### If an export operation (save or print) fails because the configured font doesn't support the more esoteric Unicode characters (e.g. the embedded Helvetica font), switch to one of the system-supplied fonts (NotoSan, LiberationSans) via the preferences panel (offered only when available on the host). This may occur when ''recipe'' data originates via a website scrape.
#* [['#XML'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
### You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
### 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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. The application anonymously informs the home site concerning the disposition of the update's download (controllable via the LogToServer preference).
# 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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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).
#; LogToServer
#: Enables minimal, anonymous, application-to-server, metric logging (as feedback for devOps to gauge application efficacy).
#; 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%20FDC'|USDA FDC API KEY]] that is used to uniquely identify the user of the FDC service,
#; FdcUrl
#: Specifies the FoodData Central internet server from which food product and nutrition 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.
#; OutputAllData
#: Specifies whether all object data (vs. a minimal subset) is output during PDF generation.
#; OutputDefaultFormat
#: Specifies the default document format to be presented for an export operation (alternatives may be subsequently chosen).
#; OutputPerPage
#: Specifies whether each object starts on a new page during PDF generation into a single document.
#; OutputFileSelection
#: Specifies whether the file chooser prompt (for location and filename) is enabled.
#; OutputFont
#: Specifies the font that is used for PDF document generation.
#; OutputConsolidatedPdfFile
#: Specifies whether all objects are consolidated into a single document during PDF generation (vs. each to a separate document).
#; OutputConsolidatedXmlFile
#: Specifies whether all objects are consolidated into a single document during XML generation (vs. each to a separate document).
#; 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.

{| class="wikitable"
|+ 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 || y || y || y || y
|-
|DietaryReference || 2 || n || y || y || n
|-
|Foods || 2 || y || y || y || y
|-
|FoodUnits || 2 || n || y || y || n
|-
|LanguageReference || 2 || n || y || y || n
|-
|Meals || 2,3 || y || y || y || y
|-
|Notes || 2 || n || y || y || n
|-
|NutrientReference || 2 || n || y || y || n
|-
|Nutrients || 2 || n || y || y || n
|-
|NutritionProfiles || 2 || y || y || y || y
|-
|Quotes || 2 || n || y || y || n ||
|-
|Recipes || 2,3 || y || y || y || y
|-
|RetentionFactors || 2 || n || y || y || n
|-
|Substitutes || 2 || y || y || y || y
|-
|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 and the OutputSinglePdfFile and OutputPerPage options are enabled.


===== 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
### Via the context menu of a ''note'' you can view or copy the whole table's content.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is. All the ''tag'' combo boxes in this section are searchable (one may enter filtering text to limit what's shown) and multi-selection (one may check multiple items per each combo box).
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### The active system properties 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted application preferences tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* PDF - [https://en.wikipedia.org/wiki/PDF Portable Data Format]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 23 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 25-ea+24 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.2.0-20250812-182757.f621a1c || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.14.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20250517 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.19.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [https://jsoup.org/ jsoup] || 1.21.1 || Runtime || [https://github.com/jhy/jsoup/blob/master/LICENSE MIT] || HTML parser, built for HTML editing, cleaning, scraping, and XSS safety.
|-
| [http://unirest.io/ Unirest Java] || 4.5.12 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.25.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 3.0.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/vandeseer/easytable easytable] || 1.0.2 || Runtime || MIT || Library providing PDF table layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.2 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.9.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.4.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 76.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.13.1 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2026-02-14T00:20:04Z

Admin: Changed protection settings for "User's Manual" ([Edit=Allow only autoconfirmed users] (indefinite) [Move=Allow only autoconfirmed users] (indefinite))

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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.
# The application has multiple actions that may be performed upon its data.
#* The save operation is used to persist data within the application's database or preferences file.
#* The print operation is used to transmit application data to a printer (as PDF).
#* The export operation is used to save application data to a file (as PDF or XML).
# Formats currently supported for application data.
#* [['#PDF'|PDF]]-based files are used to export application data. For quick access, paste your favorite recipes on your refridgerator or affix them to your children's foreheads.
### You can output your data to PDF files or the printer to gift.
### If an export operation (save or print) fails because the configured font doesn't support the more esoteric Unicode characters (e.g. the embedded Helvetica font), switch to one of the system-supplied fonts (NotoSan, LiberationSans) via the preferences panel (offered only when available on the host). This may occur when ''recipe'' data originates via a website scrape.
#* [['#XML'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
### You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
### 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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. The application anonymously informs the home site concerning the disposition of the update's download (controllable via the LogToServer preference).
# 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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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).
#; LogToServer
#: Enables minimal, anonymous, application-to-server, metric logging (as feedback for devOps to gauge application efficacy).
#; 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%20FDC'|USDA FDC API KEY]] that is used to uniquely identify the user of the FDC service,
#; FdcUrl
#: Specifies the FoodData Central internet server from which food product and nutrition 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.
#; OutputAllData
#: Specifies whether all object data (vs. a minimal subset) is output during PDF generation.
#; OutputDefaultFormat
#: Specifies the default document format to be presented for an export operation (alternatives may be subsequently chosen).
#; OutputPerPage
#: Specifies whether each object starts on a new page during PDF generation into a single document.
#; OutputFileSelection
#: Specifies whether the file chooser prompt (for location and filename) is enabled.
#; OutputFont
#: Specifies the font that is used for PDF document generation.
#; OutputConsolidatedPdfFile
#: Specifies whether all objects are consolidated into a single document during PDF generation (vs. each to a separate document).
#; OutputConsolidatedXmlFile
#: Specifies whether all objects are consolidated into a single document during XML generation (vs. each to a separate document).
#; 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.

{| class="wikitable"
|+ 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 || y || y || y || y
|-
|DietaryReference || 2 || n || y || y || n
|-
|Foods || 2 || y || y || y || y
|-
|FoodUnits || 2 || n || y || y || n
|-
|LanguageReference || 2 || n || y || y || n
|-
|Meals || 2,3 || y || y || y || y
|-
|Notes || 2 || n || y || y || n
|-
|NutrientReference || 2 || n || y || y || n
|-
|Nutrients || 2 || n || y || y || n
|-
|NutritionProfiles || 2 || y || y || y || y
|-
|Quotes || 2 || n || y || y || n ||
|-
|Recipes || 2,3 || y || y || y || y
|-
|RetentionFactors || 2 || n || y || y || n
|-
|Substitutes || 2 || y || y || y || y
|-
|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 and the OutputSinglePdfFile and OutputPerPage options are enabled.


===== 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
### Via the context menu of a ''note'' you can view or copy the whole table's content.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is. All the ''tag'' combo boxes in this section are searchable (one may enter filtering text to limit what's shown) and multi-selection (one may check multiple items per each combo box).
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### The active system properties 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted application preferences tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* PDF - [https://en.wikipedia.org/wiki/PDF Portable Data Format]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 23 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 25-ea+24 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.2.0-20250812-182757.f621a1c || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.14.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20250517 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.19.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [https://jsoup.org/ jsoup] || 1.21.1 || Runtime || [https://github.com/jhy/jsoup/blob/master/LICENSE MIT] || HTML parser, built for HTML editing, cleaning, scraping, and XSS safety.
|-
| [http://unirest.io/ Unirest Java] || 4.5.12 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.25.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 3.0.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/vandeseer/easytable easytable] || 1.0.2 || Runtime || MIT || Library providing PDF table layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.2 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.9.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.4.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 76.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.13.1 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2026-02-14T00:17:53Z

Admin: Protected "User's Manual" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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.
# The application has multiple actions that may be performed upon its data.
#* The save operation is used to persist data within the application's database or preferences file.
#* The print operation is used to transmit application data to a printer (as PDF).
#* The export operation is used to save application data to a file (as PDF or XML).
# Formats currently supported for application data.
#* [['#PDF'|PDF]]-based files are used to export application data. For quick access, paste your favorite recipes on your refridgerator or affix them to your children's foreheads.
### You can output your data to PDF files or the printer to gift.
### If an export operation (save or print) fails because the configured font doesn't support the more esoteric Unicode characters (e.g. the embedded Helvetica font), switch to one of the system-supplied fonts (NotoSan, LiberationSans) via the preferences panel (offered only when available on the host). This may occur when ''recipe'' data originates via a website scrape.
#* [['#XML'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
### You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
### 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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. The application anonymously informs the home site concerning the disposition of the update's download (controllable via the LogToServer preference).
# 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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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).
#; LogToServer
#: Enables minimal, anonymous, application-to-server, metric logging (as feedback for devOps to gauge application efficacy).
#; 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%20FDC'|USDA FDC API KEY]] that is used to uniquely identify the user of the FDC service,
#; FdcUrl
#: Specifies the FoodData Central internet server from which food product and nutrition 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.
#; OutputAllData
#: Specifies whether all object data (vs. a minimal subset) is output during PDF generation.
#; OutputDefaultFormat
#: Specifies the default document format to be presented for an export operation (alternatives may be subsequently chosen).
#; OutputPerPage
#: Specifies whether each object starts on a new page during PDF generation into a single document.
#; OutputFileSelection
#: Specifies whether the file chooser prompt (for location and filename) is enabled.
#; OutputFont
#: Specifies the font that is used for PDF document generation.
#; OutputConsolidatedPdfFile
#: Specifies whether all objects are consolidated into a single document during PDF generation (vs. each to a separate document).
#; OutputConsolidatedXmlFile
#: Specifies whether all objects are consolidated into a single document during XML generation (vs. each to a separate document).
#; 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.

{| class="wikitable"
|+ 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 || y || y || y || y
|-
|DietaryReference || 2 || n || y || y || n
|-
|Foods || 2 || y || y || y || y
|-
|FoodUnits || 2 || n || y || y || n
|-
|LanguageReference || 2 || n || y || y || n
|-
|Meals || 2,3 || y || y || y || y
|-
|Notes || 2 || n || y || y || n
|-
|NutrientReference || 2 || n || y || y || n
|-
|Nutrients || 2 || n || y || y || n
|-
|NutritionProfiles || 2 || y || y || y || y
|-
|Quotes || 2 || n || y || y || n ||
|-
|Recipes || 2,3 || y || y || y || y
|-
|RetentionFactors || 2 || n || y || y || n
|-
|Substitutes || 2 || y || y || y || y
|-
|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 and the OutputSinglePdfFile and OutputPerPage options are enabled.


===== 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
### Via the context menu of a ''note'' you can view or copy the whole table's content.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is. All the ''tag'' combo boxes in this section are searchable (one may enter filtering text to limit what's shown) and multi-selection (one may check multiple items per each combo box).
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### The active system properties 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted application preferences tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* PDF - [https://en.wikipedia.org/wiki/PDF Portable Data Format]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 23 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 25-ea+24 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.2.0-20250812-182757.f621a1c || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.14.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20250517 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.19.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [https://jsoup.org/ jsoup] || 1.21.1 || Runtime || [https://github.com/jhy/jsoup/blob/master/LICENSE MIT] || HTML parser, built for HTML editing, cleaning, scraping, and XSS safety.
|-
| [http://unirest.io/ Unirest Java] || 4.5.12 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.25.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 3.0.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/vandeseer/easytable easytable] || 1.0.2 || Runtime || MIT || Library providing PDF table layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.2 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.9.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.4.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 76.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.13.1 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2025-08-13T16:22:04Z

Admin: Searchable, multi-selection combo boxes (v0.48.2)

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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.
# The application has multiple actions that may be performed upon its data.
#* The save operation is used to persist data within the application's database or preferences file.
#* The print operation is used to transmit application data to a printer (as PDF).
#* The export operation is used to save application data to a file (as PDF or XML).
# Formats currently supported for application data.
#* [['#PDF'|PDF]]-based files are used to export application data. For quick access, paste your favorite recipes on your refridgerator or affix them to your children's foreheads.
### You can output your data to PDF files or the printer to gift.
### If an export operation (save or print) fails because the configured font doesn't support the more esoteric Unicode characters (e.g. the embedded Helvetica font), switch to one of the system-supplied fonts (NotoSan, LiberationSans) via the preferences panel (offered only when available on the host). This may occur when ''recipe'' data originates via a website scrape.
#* [['#XML'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
### You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
### 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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. The application anonymously informs the home site concerning the disposition of the update's download (controllable via the LogToServer preference).
# 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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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).
#; LogToServer
#: Enables minimal, anonymous, application-to-server, metric logging (as feedback for devOps to gauge application efficacy).
#; 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%20FDC'|USDA FDC API KEY]] that is used to uniquely identify the user of the FDC service,
#; FdcUrl
#: Specifies the FoodData Central internet server from which food product and nutrition 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.
#; OutputAllData
#: Specifies whether all object data (vs. a minimal subset) is output during PDF generation.
#; OutputDefaultFormat
#: Specifies the default document format to be presented for an export operation (alternatives may be subsequently chosen).
#; OutputPerPage
#: Specifies whether each object starts on a new page during PDF generation into a single document.
#; OutputFileSelection
#: Specifies whether the file chooser prompt (for location and filename) is enabled.
#; OutputFont
#: Specifies the font that is used for PDF document generation.
#; OutputConsolidatedPdfFile
#: Specifies whether all objects are consolidated into a single document during PDF generation (vs. each to a separate document).
#; OutputConsolidatedXmlFile
#: Specifies whether all objects are consolidated into a single document during XML generation (vs. each to a separate document).
#; 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.

{| class="wikitable"
|+ 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 || y || y || y || y
|-
|DietaryReference || 2 || n || y || y || n
|-
|Foods || 2 || y || y || y || y
|-
|FoodUnits || 2 || n || y || y || n
|-
|LanguageReference || 2 || n || y || y || n
|-
|Meals || 2,3 || y || y || y || y
|-
|Notes || 2 || n || y || y || n
|-
|NutrientReference || 2 || n || y || y || n
|-
|Nutrients || 2 || n || y || y || n
|-
|NutritionProfiles || 2 || y || y || y || y
|-
|Quotes || 2 || n || y || y || n ||
|-
|Recipes || 2,3 || y || y || y || y
|-
|RetentionFactors || 2 || n || y || y || n
|-
|Substitutes || 2 || y || y || y || y
|-
|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 and the OutputSinglePdfFile and OutputPerPage options are enabled.


===== 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
### Via the context menu of a ''note'' you can view or copy the whole table's content.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is. All the ''tag'' combo boxes in this section are searchable (one may enter filtering text to limit what's shown) and multi-selection (one may check multiple items per each combo box).
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### The active system properties 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted application preferences tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* PDF - [https://en.wikipedia.org/wiki/PDF Portable Data Format]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 23 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 25-ea+24 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.2.0-20250812-182757.f621a1c || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.14.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20250517 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.19.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [https://jsoup.org/ jsoup] || 1.21.1 || Runtime || [https://github.com/jhy/jsoup/blob/master/LICENSE MIT] || HTML parser, built for HTML editing, cleaning, scraping, and XSS safety.
|-
| [http://unirest.io/ Unirest Java] || 4.5.12 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.25.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 3.0.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/vandeseer/easytable easytable] || 1.0.2 || Runtime || MIT || Library providing PDF table layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.2 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.9.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.4.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 76.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.13.1 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2025-07-05T19:06:56Z

Admin: Maintenance release consisting of bug and annoyance fixes (v0.48.1).

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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.
# The application has multiple actions that may be performed upon its data.
#* The save operation is used to persist data within the application's database or preferences file.
#* The print operation is used to transmit application data to a printer (as PDF).
#* The export operation is used to save application data to a file (as PDF or XML).
# Formats currently supported for application data.
#* [['#PDF'|PDF]]-based files are used to export application data. For quick access, paste your favorite recipes on your refridgerator or affix them to your children's foreheads.
### You can output your data to PDF files or the printer to gift.
#* [['#XML'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
### You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
### 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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. The application anonymously informs the home site concerning the disposition of the update's download (controllable via the LogToServer preference).
# 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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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).
#; LogToServer
#: Enables minimal, anonymous, application-to-server, metric logging (as feedback for devOps to gauge application efficacy).
#; 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%20FDC'|USDA FDC API KEY]] that is used to uniquely identify the user of the FDC service,
#; FdcUrl
#: Specifies the FoodData Central internet server from which food product and nutrition 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.
#; OutputAllData
#: Specifies whether all object data (vs. a minimal subset) is output during PDF generation.
#; OutputDefaultFormat
#: Specifies the default document format to be presented for an export operation (alternatives may be subsequently chosen).
#; OutputPerPage
#: Specifies whether each object starts on a new page during PDF generation into a single document.
#; OutputConsolidatedPdfFile
#: Specifies whether all objects are consolidated into a single document during PDF generation (vs. each to a separate document).
#; OutputConsolidatedXmlFile
#: Specifies whether all objects are consolidated into a single document during XML generation (vs. each to a separate document).
#; OutputFileSelection
#: Specifies whether the file chooser prompt (for location and filename) is enabled.
#; 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.

{| class="wikitable"
|+ 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 || y || y || y || y
|-
|DietaryReference || 2 || n || y || y || n
|-
|Foods || 2 || y || y || y || y
|-
|FoodUnits || 2 || n || y || y || n
|-
|LanguageReference || 2 || n || y || y || n
|-
|Meals || 2,3 || y || y || y || y
|-
|Notes || 2 || n || y || y || n
|-
|NutrientReference || 2 || n || y || y || n
|-
|Nutrients || 2 || n || y || y || n
|-
|NutritionProfiles || 2 || y || y || y || y
|-
|Quotes || 2 || n || y || y || n ||
|-
|Recipes || 2,3 || y || y || y || y
|-
|RetentionFactors || 2 || n || y || y || n
|-
|Substitutes || 2 || y || y || y || y
|-
|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 and the OutputSinglePdfFile and OutputPerPage options are enabled.


===== 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is.
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### The active system properties 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted application preferences tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* PDF - [https://en.wikipedia.org/wiki/PDF Portable Data Format]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 22 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 25-ea+23 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.2.0-20250608-090535.869f248 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.132.0.27.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20250517 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.19.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [https://jsoup.org/ jsoup] || 1.21.1 || Runtime || [https://github.com/jhy/jsoup/blob/master/LICENSE MIT] || HTML parser, built for HTML editing, cleaning, scraping, and XSS safety.
|-
| [http://unirest.io/ Unirest Java] || 4.4.7 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.25.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 3.0.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/vandeseer/easytable easytable] || 1.0.2 || Runtime || MIT || Library providing PDF table layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.2 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.9.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.4.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 76.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.13.1 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2025-06-06T21:19:26Z

Admin: Updated PDF output (printer and file) for Recipe, Meal, Food, Substitute and Profile objects. (V0.48.0)

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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.
# The application has multiple actions that may be performed upon its data.
#* The save operation is used to persist data within the application's database or preferences file.
#* The print operation is used to transmit application data to a printer (as PDF).
#* The export operation is used to save application data to a file (as PDF or XML).
# Formats currently supported for application data.
#* [['#PDF'|PDF]]-based files are used to export application data. For quick access, paste your favorite recipes on your refridgerator or affix them to your children's foreheads.
### You can output your data to PDF files or the printer to gift.
#* [['#XML'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
### You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
### 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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%20FDC'|USDA FDC API KEY]] that is used to uniquely identify the user of the FDC service,
#; FdcUrl
#: Specifies the FoodData Central internet server from which food product and nutrition 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.
#; OutputAllData
#: Specifies whether all object data (vs. a minimal subset) is output during PDF generation.
#; OutputDefaultFormat
#: Specifies the default document format to be presented for an export operation (alternatives may be subsequently chosen).
#; OutputPerPage
#: Specifies whether each object starts on a new page during PDF generation into a single document.
#; OutputConsolidatedPdfFile
#: Specifies whether all objects are consolidated into a single document during PDF generation (vs. each to a separate document).
#; OutputConsolidatedXmlFile
#: Specifies whether all objects are consolidated into a single document during XML generation (vs. each to a separate document).
#; OutputFileSelection
#: Specifies whether the file chooser prompt (for location and filename) is enabled.
#; 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.

{| class="wikitable"
|+ 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 || y || y || y || y
|-
|DietaryReference || 2 || n || y || y || n
|-
|Foods || 2 || y || y || y || y
|-
|FoodUnits || 2 || n || y || y || n
|-
|LanguageReference || 2 || n || y || y || n
|-
|Meals || 2,3 || y || y || y || y
|-
|Notes || 2 || n || y || y || n
|-
|NutrientReference || 2 || n || y || y || n
|-
|Nutrients || 2 || n || y || y || n
|-
|NutritionProfiles || 2 || y || y || y || y
|-
|Quotes || 2 || n || y || y || n ||
|-
|Recipes || 2,3 || y || y || y || y
|-
|RetentionFactors || 2 || n || y || y || n
|-
|Substitutes || 2 || y || y || y || y
|-
|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 and the OutputSinglePdfFile and OutputPerPage options are enabled.


===== 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is.
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### The active system properties 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted application preferences tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* PDF - [https://en.wikipedia.org/wiki/PDF Portable Data Format]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 22 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 25-ea+18 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.2.0-20250509-104313.02c1bcb || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.132.0.27.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20250517 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.19.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [http://unirest.io/ Unirest Java] || 4.4.7 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.24.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 3.0.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/vandeseer/easytable easytable] || 1.0.2 || Runtime || MIT || Library providing PDF table layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.2 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.7.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.4.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 76.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.13.0 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2025-02-21T19:35:33Z

Admin: Component Query panel and robustness (v0.47.0)

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
## You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
## 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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%20FDC'|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.

{| class="wikitable"
|+ 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is.
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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.


==== Component Query Panel ====

# Purpose
## Used to identify ''food'' products that contain a desired component (e.g. a ''nutrient'') per various portions. The table of results allow comparisons to be made.
### The product listing is the result of a database query to an internet site that allows the user to select the best ''food'' per need. The FDC is the only data provider for the panel at this time.
### Then, when one or more ''food'' products are selected, component concentration per additional, pre-defined portions can be retrieved via the Query Portions button.
### The Desired Portion control logic allows a custom amount of ''food'' to be specified to determine how much of the component is available in that portion.
# Controls
## When set (enabled), the Query On Change radio button allows a data request to be immediately initiated for any change made to any of the input controls (e.g. Category, Descriptors, Description-only / Data Type). If you'd prefer to enter data in several of the controls, but not kick-off a data request until you finally make a selection via the Component combo box, then first unset (disable) the Query On Change radio button. The data request will then be initiated when the Component combo box selection is changed (at the end of your typing flurry).
## The Category combo box can be used to query for ''foods'' associated with a selected category.
## The Descriptors text box can be used to query for those ''foods'' that have any of the specified words located in (possibly) multiple fields of the ''food's'' data record. If the Description-only radio button is set (enabled), then the word search is limited to only the description field in the ''food's'' data record.
## By default, when the Show All Hits radio button is not set (disabled), the number of ''food'' products retrieved by the component search is limited to a predetermined maximum (so as not to make the internet huff and puff). If you see that a bigger result set count is available via the Disposition label text, and you want it in a really bad way, then enable that radio button to re-query for all of those puppies. For large result sets, "smoke 'em if you got 'em". If you're agast at the number of cycles you've mischievously initiated, you can always hit that little X thingy in the upper right-hand corner to exit the panel. This cancels the message storm which would have finished eventually you gutless oaf.
# Tips
## While those of a wily nature would expect the capability to simultaneously specify multiple input values to narrowly filter a result set down to a minimual number of ''foods'' where each would have all of the targetted characteristics (e.g. an intersection in set theory), that's not the way this game works, my bucko. The underlying paradigm here is more additive (e.g. a union in set theory) with respect to the ''foods'' that have been snared in that gnarly net you've cast. Heavy sigh.
## The rest should be self-explanatory. Play with the panel a bit. You'll get it. Eventually.


==== Food Query Panel ====

# Purpose
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### The text in the query text box (add or remove characteristics of the food),
### Toy with either of the two require options:
#### When enabled, the Require All Words option requests only those ''food'' products that have all of the words (in no particular order in the query text box) in their data record. When disabled, ''food'' products are requested that have any of the words specified in the query text box in their data record.
#### When enabled, the Require Exact Match option requests only those ''food'' products that have the complete phrase (ordered as-is in the query text box) in their data.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted preferences values tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 22 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 25-ea+2 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.2.0-20250219-143145.6c030f7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.13.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.18.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.4.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20250107 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.18.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [http://unirest.io/ Unirest Java] || 4.4.5 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.24.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 2.0.27 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/ralfstuckert/pdfbox-layout Pdfbox2 Layout] || 1.0.1 || Runtime || MIT || Library providing PDF text layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.1 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.7.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 76.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.11.4 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2024-12-31T22:47:21Z

Admin: Staged ingredients, fractional compound units, XML changes (v0.46.2)

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
## You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
## 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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''.
# For those panels based upon the included web engine (e.g. web browser and help), the search functionality works best on static web page content. Dynamically-generated web pages (i.e. pages that have content generated via script execution) can be unparsable by the application.

=== Behavior ===

==== XML Importation ====

# When importing internal objects from XML files:
## You may import from the same filename any number of times, but only those managed 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 in any way.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## If not all of the desired managed objects are imported, you can change the log level setting to TRACE (via the preferences panel), launch the console panel, re-import your XML file, and wade through the application trace logs to identify which XML tag(s) or value(s) may be causing you grief. Then correct said irritant and try again, Finnegan.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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. WRT searchable combo boxes whose selections aggregate into a set (as displayed in an adjacent text area): in addition to selecting an entry via mouse-click or a keyboard's enter key, in a few cases one also selects multiple entries just by using the up / down arrow keys to meander to a final entry. If you don't wish those extra entries, either remove them from the text area before saving, or limit the size of the filtered items that are displayed by entering a more accurate character sequence.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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%20FDC'|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.

{| class="wikitable"
|+ 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
## After selecting one or more rows in the ''ingredient'' table, you may assign color-coded stages via the context menu that's available via a secondary button-click of the mouse. Grouping the ''ingredients'' under a common stage (and color) allows you to more easily reference different stages from the directions section of the ''recipe''.
## To reposition one or more ''ingredient'' rows within the table, first select those desired, and then apply the up / down arrow key while the control key is depressed.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is.
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### the text in the query text box (add or remove characteristics of the food),
### change the "Require All Words" or "Require Exact Match" options.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## The traces displayed are a function of the log level setting in the preferences panel. The more detailed the log level selection (i.e. the less severe), the greater the number of traces produced (and the slower the application executes).
# Controls
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Browser Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted preferences values tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 22 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 24-ea+15 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.1.1-20241116-021934.5be16ea || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.3 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.13.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.4.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20240303 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.18.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [http://unirest.io/ Unirest Java] || 4.4.5 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.23.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 2.0.27 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/ralfstuckert/pdfbox-layout Pdfbox2 Layout] || 1.0.1 || Runtime || MIT || Library providing PDF text layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.1 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.7.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 76.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.11.3 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2024-09-12T00:10:27Z

Admin: Webscrape capability (v0.46.0) - add Schema.org citation

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
## You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
## 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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:
## 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.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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%20FDC'|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.

{| class="wikitable"
|+ 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is.
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### the text in the query text box (add or remove characteristics of the food),
### change the "Require All Words" or "Require Exact Match" options.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## 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
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted preferences values tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 22 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 24-ea+5 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.1.0-20240829-135020.8bbac7f || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.11.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.15.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20240303 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [http://unirest.io/ Unirest Java] || 4.4.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.23.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 2.0.27 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/ralfstuckert/pdfbox-layout Pdfbox2 Layout] || 1.0.1 || Runtime || MIT || Library providing PDF text layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.1 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.6.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 75.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.11.0 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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
|-
| [https://schema.org/Recipe Schema.org Recipe type (and all supporting types)] || Version 27.02, without change || [https://creativecommons.org/licenses/by-sa/3.0/ CC BY-SA 3.0] || [https://schema.org/docs/about.html About Schema.org]
|}

User's Manual

2024-09-11T15:27:23Z

Admin: Webscrape capability (v0.46.0)

__TOC__


= 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%20Objects'|internal objects]] must have a unique [['#Descriptor'|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''.
## ''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.
## ''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.
## 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).
## ''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'|XML]]-based files are used to import and export application data. Trade them with your friends (like baseball cards).
## You can export your data to XML files and store them in a safe place as a backup. Like at Gringott's.
## 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''
## Displayed ''nutrition'' shows both an absolute amount and the [['#DRI'|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).
## 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.
## 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:
## 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.
## 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''.
## Imported ''recipes'' are listed in the import tab (a staging area) where the following actions may be performed.
### 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.
### 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.
### Any ''recipes'' not saved from the import tab are discarded upon application exit.
### 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.
### 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.
## 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.

{| class="wikitable"
|+ 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'|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'|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.
##LanguageReference
##FoodUnit
##Tag
##DietaryReference
##NutrientReference
##Nutrient
##RetentionFactor
##YieldFactor
##Food
##ConversionProfile
##NutritionProfile
##Note
##Quote
##Recipe
##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.</li>
#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'|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: [https://fdc.nal.usda.gov/api-key-signup.html 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:
## It may inadvertently fall over and wheeze.
## It may offer erroneous data (although the Author is extraordinarily diligent at verifying the integrity of the data and calculations).
## It does not imply applicability to any insidious purpose you may conjure up in that warped mind of yours.
## 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.
## 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
## My artwork.
## My patience with unhelpful, nonconstructive feedback.
## 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.
## 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.
## 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.
## Importation of various file formats (e.g. PDF).
## 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:
## Measurement
### A ''conversion profile'' defines one or more conversions between two or more equivalent [['#Portion'|portions]], that are unique to a specified ''food'' or ''food''-type.
#### 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).
#### 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).
#### A ''conversion profile'' is required by the application for conversion between dissimilar units (unless you enjoy angry status messages / pop-up notifications).
### A ''food unit'' (a ''keyword'') is a unit of measure applicable to ''food'' (e.g. cup, not parsec)
### A ''measurement'' is an amount of something. Akin to portion.
## Nutrition
### 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.
### 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.
### 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''.
### 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''.
### A ''nutrition profile'' defines food product meta data (IDs, production, components, analysis) for the one, unique ''nutrition'' that it references.
### 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''.
## Organization
### ''Keywords'' are sets of words assigned into a classification, used to describe other objects, and to support certain user actions.
### 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).
## Planning
### A ''meal'' is a composed of one or more ''servings'' that has its own ''nutrition summary'' and scheduling information.
### A ''serving'' is a portion of a ''recipe'', that has its own ''nutrition summary'' and that is assignable to a ''meal''.
## Recipe
### 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.
### An ''ingredient'' defines a portion of an edible (i.e. a ''food'' or another ''recipe'') that can have defined characteristics.
### A ''recipe'' is a collection of ''ingredients'' and / or other ''recipes'' with preparation instructions with defined characteristics.
## Supplemental
### 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.
### 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:
## The meal-planning ''calendar'' allows ''meals'' to be created and allocated across one or more days per scheduling rules.
## A ''calendar entry'' can be a ''meal entry'' or a ''day aggregator entry''.
## A ''meal entry'' represents a ''meal'' scheduled on a day or recurring across several, possibly nonconsecutive, days.
## 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 [['#ArtifactDirectory'|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%20FDC'|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.

{| class="wikitable"
|+ 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 [https://docs.oracle.com/cd/E17277_02/html/java/com/sleepycat/je/EnvironmentConfig.html 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
## Provides display, search, and management of user-defined ''recipes'' and ''notes''
# Actions
## The search tab supports searches for ''recipes'' whose descriptor, classifiers, and / or source contain the specified tags.
## The search ''nutrition'' tab supports searches for ''recipes'' whose ''nutrition'' matches user-defined ''nutrient'' amounts.
## The browser tab lists all ''recipes'' that may be used / modified.
## The import tab lists imported ''recipes'' that may be selected and saved, if desired.
## 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 [https://schema.org/Recipe schema.org/Recipe] type).
## The notes tab supports hierarchical display and management of ''notes'', presumedly related to ''food''-like musings.
# Controls
## 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 ...".
## The status bar background is color-coded with respect to message severity as follows: Hello Debug Note Warning Error 
## You can initiate an update request via the Help > Check for update menu item.
## 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.
## 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.
## 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
## From any table of recipes, you can primary mouse button double-click to see a summary of the ''recipe'' in the recipe card panel.
## From the search tab, you can:
### Enter any number of comma-delimited tags to search for those recipes that are labeled with those tags.
### 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.
### 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).
### 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).
### Entered text with no commas is considered a single search token.
## From the search ''nutrition'' tab, you can:
### 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.
### Recipes that match all of the criteria are listed in the search tab.
### Listed recipes are those that have ''nutrition'' defined where the per serving nutrient amount matches or exceeds the specified nutrient amount.
## From the browse tab, you can:
### 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.
## From the import tab, you can:
### 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.
## From the notes tab, anywhere in the hierarchy under the ''Library'' topic, you can:
### 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.
### Move the little buggers around the hierarchy as you see fit.
### The ''Library'' and ''Orphan'' topics cannot be removed and are required by the application for proper function.
### 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.
### 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.
### 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.
## 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.
## 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
## The ''meal calendar'' displays and allows time-management of ''meal'' entries to support meal-planning. A ''meal'' entry presents its ''nutrition''.
## 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''.
## A ''nutrition summary'' is displayed in the calendar entry whereas all available ''nutrition'' is available via its context menu.
## The ''agenda view'' provides a look-ahead and look-behind list of ''meals''.
# Actions
## To add a ''meal'', primary mouse button double-click in the ''meal calendar'' at the desired start time.
## To remove a ''meal'', select it and depress the delete key.
## By right-clicking on a ''meal'', you can select the following options:
### View nutrition displays a read-only summary view of the ''meal's nutrition''.
### View servings displays a read-only summary view of the ''meal's servings''.
### 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.
### Edit meal launches the meal's edit panel to allow its ''serving'' data to modified.
### Print meal prints the meal. Doh!
### Delete Meal permanently removes the ''meal'' and the day's aggregate ''nutrition'' is automatically updated as a result.
## 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''.
## To change the look-ahead / look-behind time span for the ''agenda view'', right-click and follow your instincts.
# Controls
## 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.
## 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.
## ''meal'' entries are viewable for a given day, week, month, or year time period.
## 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.
## Concerning calendar entries:
### The application only saves entry data from the ''meal calendar''.
### ''Aggregator calendar'' entries are auto-magically created when at least one ''meal'' entry exists for that day.
# Tips
## Scheduling
### 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).
### 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
## Provides display and management of both pre-defined and any new, user-defined ''foods''
# Actions
## Use the add button to define a new ''food''.
## Primary mouse button double-click an existing ''food'' to edit its characteristics.
## 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
## 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
## Provides display and management of all ''substitutes'' that exist for all ''foods''.
# Actions
## Use the add button to define a new ''substitute'' for a new ''food''.
## Primary mouse button double-click an existing ''food substitute'' to edit its characteristics.
# Controls
# Tips
## Keep your cake moist by eating it in one sitting.


==== Tags Panel ====

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


==== Tree Panel ====

# Purpose
## Displays all ''nutrients'' or ''food units'' as a hierarchical tree where the selected item's data is presented via table.
# Actions
## Define a new ''keyword'' via the add button.
## Search for a case-sensitive word or fragment via the search text box.
## Open or close the entire tree hierarchy via the expand / collapse radio button.
# Controls
## A primary mouse button double-click will open / close the selected branch.
# Tips
## 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
## Provides display, search, and management of user-defined ''meals''.
# Actions
## 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).
## The meal tab lists all ''meals'' that are available.
## Primary mouse button double-click to modify the characteristics of a particular ''meal''.
## Secondary mouse button single-click to access a context menu providing per ''meal'' actions.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''meals''.
### 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).
## Concerning a ''meal's'' start date and recurrence rule:
### They are read-only at the meals panel and are not changeable at the meal panel.
### They may only be changed at the calendar panel (which is used for meal-planning).
### 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).
## 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
## Provides display, search, and management of user-defined ''conversion profiles'' and ''nutrition profiles''.
# Actions
## The search tab supports lookup of profiles of any type whose descriptor contain the specified tags.
## The conversion tab lists all available ''conversion profiles'' that may be applied or modified.
## The nutrition tab lists all available ''nutrition profiles'' that may be applied or modified.
## The shopping tab will, one day, whisk into existence in a bang reminiscent of the big one.
## Primary mouse button double-click to modify the characteristics of a particular ''profile''.
# Controls
# Tips
## From the search tab, you can:
### Enter any number of comma-delimited words to search for a set of ''profiles''.
### 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
## Provides display and management of any user-defined ''quotes''
# Actions
## 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.
## 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.
## 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.
## A delete permanently removes the selected ''quote''.
# Controls
# Tips
## No color change hints for edits are provided since updated ''quote'' fields are automatically saved.
## 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
## 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''.
## 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.
## Can greatly improve accuracy during ''nutrition'' construction.
# Actions
## Add equivalent portions (with dissimilar units), with a unique descriptor, to define accurate conversions for the specified ''food'' type or product.
## Copy the equivalent portions from another ''conversion profile'' and update as desired.
## Attribute your conversion data to its source if your nicking it from some other world.
# Controls
# Tips
## The ''descriptor'' of a ''conversion profile'' must:
### be unique, and
### exactly match a ''food'' type or product descriptor that is used in recipes.
## To remove, highlight one or more portions and depress the delete key.
## Imported ''conversion profiles'' will automatically be assigned to a ''food'' with the same name.


==== Keyword Panel ====

# Purpose
## 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
## Add, edit the characteristics of, or delete a ''keyword''.
## The characteristics defined and available for change are a function of the classification (type) of ''keyword''.
# Controls
# Tips
## When modifying a ''food'':
### You can add nutrition data which can later be used as a source during construction of nutrition data for a ''recipe''.
### 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.
## ''Food units'' and ''nutrients'' are partitioned as either user-defined or system-defined with the following limitations:
### System-defined keywords are not deletable (given their mission critical nature)
### Properties that cannot be modified have their supporting GUI widgets (e.g. combo-box, text field) disabled.
### 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.
### 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.
### 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
## Provides definition and management of a ''meal''.
# Actions
## Add a ''serving'', with a meal-unique descriptor for a specified portion of a selected ''recipe''.
## Copy the ''serving'' entries from another ''meal'' and update any ''serving'' descriptor, ''recipe'', portion as desired.
# Controls
## 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
## 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.
## As each ''serving'' (of a ''recipe'' that has defined ''nutrition'') is added,
### A ''nutrition summary'' is displayed for the ''serving's portion''. Change the ''portion'', and you change the ''nutrition'' for that ''serving''.
### The ''meal's nutrition summary'' at the top of the panel always reflects the total summed over the ''nutrition'' data of all assigned ''servings''.
## 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
## 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
## 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.
## Add a ''nutrient'' entry and update the quantity for the default unit.
## Copy the ''nutrient'' entries from another ''nutrition profile'' and update the quantities for the default unit.
# Controls
# Tips
## 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''.
## 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
## Provides definition and management of a ''recipe''. Doh!
# Actions
## The description tab supports definition and updates for the characteristics and classifications of the ''recipe''.
## The ingredients tab lists and supports definition and updates for ''recipe'' ingredients.
## The directions tab supports definition and updates for instructions, modifications, and notes for the ''recipe''.
## Depress the recipe card button to peruse a summary of the ''recipe'' data you have saved.
## Depress the nutrition facts button to peruse, wait for it ..., the nutrition facts that you've previously retrieved and saved for your ''recipe''.
# Controls
## Use the edit>''conversion profile'' menu item to create a new or edit the ''recipe's'' currently-assigned ''conversion profile''.
# Tips
## 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:
### If the serving size unit is 'Serving', then the serving size quantity must be '1',
### 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.
## The more tags you select in the Description > Classy section of the description tab, the more searchable the ''recipe'' is.
## 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.
## 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.
## 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!
## 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).
## 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.
## 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
## ''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.
## 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.
## 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.
## 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
## Provides an, at-a-glance, read-only summary of the ''recipe''.
# Actions
## 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
## Captain, the engines cannae take much more.
# Tips
## Not all things in this world scale linearly.
## 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
## 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
## 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
## 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.
## 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''.
## 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
##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
##Context menu options applicable to one or more ''meal'' entries in the week-day and month views of the calendar are:
###View average ''nutrition'' for selected
####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.
####When used for a selection of an aggregate ''meal'' implies selection of all ''meals'' for that day.
####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.
###View average ''nutrition'' for week
####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).
###View average ''nutrition'' for month
####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.
##The following warnings may be presented within the panel:
###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)
##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.
##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
##For the option, view average ''nutrition'' for selected:
###The selected meal entry set must be homogeneous (i.e. either all aggregate entries or all meal entries),
###If no entries are explicitly selected, then the entry used is that entry over which the mouse was hovering upon the secondary button-click.
##For the option, view average ''nutrition'' for week:
###Only the last selected entry of multiple selected entries that span multiple weeks is used to determine the week used.
##For the option, view average ''nutrition'' for month:
###Only the last selected entry of multiple selected entries that span multiple months is used to determine the month used.
##For the incomplete sum warning:
###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
## 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
## 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
## The footnotes at the bottom of each tab provide hyperlinks to access source material for further enlightenment.
# Tips
## 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.
## 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
## 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
## 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
## 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.
## 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).
##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
## The default population row is identified by the default tag in the population column of each tab.
## 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.
## 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
## 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):
### 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,
### A list of ''NutritionProfile's'', that allows the user to select from any pre-defined, locally-hosted ''nutrition'' data, or
### 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).
## 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.
## Compiled / constructed ''nutrition'' values may be displayed for:
### A ''food'' in the food's edit panel,
### A ''recipe'' in the recipe's card panel or its nutritional facts panel,
### A ''meal'' and its ''servings'' in the meal's edit panel, and
### The ''calendar'' entries (both per ''meal'' and the per day ''meal aggregations'').
# Controls
## 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:
### 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).
### 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.
## Depress the next button to cycle to the next ''ingredient'' of a ''recipe''.
## You may select from multiple sources of ''nutrition'' data:
### Two sources of ''nutrition'' data are selectable via the source combo box:
###* The default is the [['#USDA%20FDC'|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.
### ''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.
## The query status line provides information concerning the query's disposition (e.g. for remote queries: HTTP status code, number retrieved vs. number available).
## Double-click on a ''food'' product to add its ''nutrition'' data into the nutrition construction panel (which is launched upon the first selection).
## 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
## The food query panel can be launched in one of two modes:
### 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.
### 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.
## 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:
### the text in the query text box (add or remove characteristics of the food),
### change the "Require All Words" or "Require Exact Match" options.
## 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!
## 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
## Provides display, management, and optionally aggregation, of ''nutrition'' data for one or more ''food'' products. The panel information is presented via two tables:
### 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''):
#### The total column displays the quantity of the nutrient summed across all ''foods/ingredients'' selected.
#### The retention column shows the total quantity for the nutrient adjusted for those selected ''retention factors'' (if any) that are pertinent to the nutrient.
#### 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'|Data Sources]] reference below).
#### 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.
### 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
## 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.
## A column may be deleted by selecting any cell in the column and depressing the delete key.
## Column header color indicates the accuracy of the initial unit conversion, if any was required, for the displayed the ''nutrition'' data.
### 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.
## 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.
## 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.
## 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.
## Factor table utilization:
### 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.
### 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").
### 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.
### 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).
## 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.
## 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
## 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.
## 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.
## 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.
## 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).
## When the nutrition construction panel is launched from its parent (hint: the food query panel), the parent's mode is inherited:
### Free form: the ''nutrition'' data displayed is applicable to (calculated from) the default portion of the selected ''food'' product or ''nutrition profile''.
### Recipe-driven: the ''nutrition'' data displayed is applicable to (calculated from) the amount specified for the ''food'' of the ''recipe's'' ''ingredient''.
## You may delete a ''food'' product's nutrition column and choose another product from the food query panel for the corresponding ''ingredient''.
## 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'':
### A validity check is performed to ensure that each non-optional ''recipe'' ''ingredient'' has ''nutrition'' data for one and only one ''food'' product.
### 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'').
### 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.
### 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.
## 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.
## If an FDC-supplied portion conversion can't be made, then:
### A ''conversion profile'' entry is used when defined (which can be brand-specific).
## 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):
### Make sure that ''ingredient'' units are a weight unit for dry edibles and a volume unit for liquids.
## 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
## Displays application processing traces (logs) for those who wish to gaze inside the application as it does its thing.
# Actions
## 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
## Clear the log in anticipation of obtaining traces for only a particular sequence of application actions.
## Select and copy those traces that you wish to relay into, say, a support email.
# Tips
## 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?
## 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
## Displays calculated conversions between units and ''attributes'' for a ''food'' that has a ''conversion profile''.
# Actions
## Enter a desired quantity and select a desired unit / attribute to watch the fireworks.
# Controls
# Tips
## At least 20%, please.


==== Graph Panel ====

# Purpose
## Provides a graphical view of the application's managed object population, structure, and data via two modes of graph operation:
### 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.
### 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
## Go 'n' play. Are you not entertained?
## When a graph is created, its nodes attempt to self-organize to provide a view that is optimally readable.
## 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.
## The graph transitions to normal mode when:
### the graph panel is first launched,
### the home button is selected,
### the back/forward button transitions to a previous graph that was presented in normal mode, or
### a primary mouse button double-click is used on a node.
## The graph transitions to walkabout mode when:
### a single-click of the mouse's secondary button is used on a node that represents a managed object, or
### the back/forward button transitions to a previous graph that was presented in walkabout mode.
# Controls
## 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).
## 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.
## Zoom in to a section of the graph by selecting a node and working that mouse wheel like there's no tomorrow.
## A node's appearence hints at its potential (much like a "come hither" look):
### 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).
### 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.
### 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).
## Drill down into a node's data set by double-clicking the primary mouse button.
## 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
## Buy low, sell high. After all, it's not a profit if you don't sell.


==== Statistics Panel ====

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


==== Web Panel ====

# Purpose
## Provides a minimal, in-application web browser
# Actions
# Controls
# Tips
## 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
## Identifies some of the application's more prosaic information: version, author, support email, license.
# Actions
## Access the Author's web-site.
## 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.
## Access the application license or the third-party package licenses.
# Controls
# Tips
## Really? For an about panel?


==== Help Panel ====

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


==== Preferences Panel ====

# Purpose
## It's here that the application pretends to care that your delicate user sensibilities will be taken into account / honored.
### 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.
### 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
## From the operational view:
### To launch the preference configuration panel, left-click the accepted preferences values tab, then the edit>preferences menu items,
### Admire the preference values that have been accepted by the application and are, therefore, currently in-effect or about to be upon restart.
## From the configuration view:
### Enter a portion of a preference name or section in the search box to locate a desired preference,
### Navigate the sections via either the tree view or the bread-crumb bar (to the right of the search box, respectively).
### Manipulate the preference values as needed: either the changes are accepted immediately or will require depressing the OK / APPLY buttons.
# Controls
# Tips
## Most of the preference fields have tool tips available (for those patient enough to hover their mouse over the desired field).
## 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).
## 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.
## Most of these preferences have their function described in the configuration files section of this help document. Additional preference setting insight:
### 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.
### 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.
### If the application doesn't detect an existing database upon startup, it will recreate the default database (that was available upon initial installation).
### 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.
### 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?
### 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 - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Adequate Intake]
* AMDR - [https://med.libretexts.org/Bookshelves/Nutrition/Book%3A_Nutrition_Science_and_Everyday_Application_(Callahan_Leonard_and_Powell)/01%3A_Designing_A_Healthy_Diet/1.05%3A_Defining_Nutrient_Requirements-_Dietary_Reference_Intakes/ Acceptable Macronutrient Distribution Range]
* DRI - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Daily Recommended Intake]
* RDA - [https://ods.od.nih.gov/HealthInformation/dailyvalues.aspx/ Recommended Dietary Allowance]
* USDA FDC - [https://fdc.nal.usda.gov/ US Department of Agriculture's FoodData Central web site]
* XML - [https://en.wikipedia.org/wiki/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?
##*The daily value percentages shown in the various nutrition views indicate how much of a nutrient's [['#RDA'|RDA]] or [['#AI'|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'|Data Sources]] section of this online help. The general population values, in contrast, are noted in the document [['https://www.fda.gov/media/134505/download|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)?
##* 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).

{| class="wikitable"
|+ Incorporated Open Source Components
|-
! Component !! Version !! Role !! License !! Comment
|-
| [https://entangledbits.org/gitea/EntangledBits/CuttingBoard/ CuttingBoard] || Latest || Runtime || [https://www.gnu.org/licenses/gpl-3.0.html GPL-3.0] || The tortured, entangled bits that are the soul of the CuttingBoard application
|-
| [https://jdk.java.net/19/ OpenJDK] || 22 || Runtime || [https://openjdk.java.net/legal/gplv2+ce.html GPL-2.0+CE] || Java Development Kit.
|-
| [https://openjfx.io/ OpenJFX] || 24-ea+5 || Runtime || [https://opensource.org/licenses/gpl-2.0.php GPL-2.0] || Java client application graphics platform.
|-
| [https://git.qoto.org/Ferma/Ferma.git Ferma] || 3.3.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || An ORM / OGM for the TinkerPop graph stack.
|-
| [https://tinkerpop.apache.org TinkerPop] || 3.5.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph computing framework for graph databases and graph analytic systems.
|-
| [https://janusgraph.org/ JanusGraph] || 1.1.0-20240829-135020.8bbac7f || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || A graph database.
|-
| [https://tinkerpop.apache.org/gremlin.html Gremlin] || 3.7.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Gremlin is the graph traversal language of Apache TinkerPop.
|-
| [https://lucene.apache.org Lucene] || 8.9.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.html Apache 2.0] || Library providing indexing and search features.
|-
| [https://www.oracle.com/database/nosql/technologies/nosql/ Oracle NoSQL DB Server] || 5.18.3.12 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0.txt Apache 2.0] || Berkeley Database Java Edition - build and runtime support.
|-
| [https://commons.apache.org/ Apache Commons Lang3] || 3.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of Java utility classes for the classes that are in / or should be in java.lang's hierarchy.
|-
| [https://commons.apache.org/ Apache Commons Text] || 1.11.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library focused on algorithms working on strings.
|-
| [https://commons.apache.org/proper/commons-math/ Apache Commons Math] || 3.6.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library of lightweight, self-contained mathematics and statistics components addressing the most common practical problems.
|-
| [https://commons.apache.org/ Apache Commons IO] || 2.15.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing utility classes, stream implementations, file filters, file comparators, endian transformation classes, ...
|-
| [https://hc.apache.org/ Apache HttpClient5] || 5.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HTTP/1.1 compliant HTTP agent implementation providing components for client-side authentication, HTTP state management, and HTTP connection management.
|-
| [https://hc.apache.org/ Apache HttpAsyncClient] || 4.1.5 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 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.
|-
| [https://hc.apache.org/ Apache HttpClient Mime] || 4.5.14 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents HttpClient - MIME coded entities.
|-
| [https://hc.apache.org/ Apache HttpCore NIO] || 4.4.16 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || HttpComponents Core (non-blocking I/O).
|-
| [http://www.JSON.org/ JSON In Java] || 20240303 || Runtime || [https://www.json.org/license.html JSON] || A reference implementation of a JSON package in Java.
|-
| [https://github.com/FasterXML/jackson-databind Jackson Databind] || 2.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || General data-binding functionality for Jackson: works on core streaming API.
|-
| [http://unirest.io/ Unirest Java] || 4.4.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Simplified, lightweight HTTP client library.
|-
| [https://github.com/dorkbox/Version/ Dorkbox Version] || 3.1 || Runtime || [https://github.com/dorkbox/Version/blob/master/LICENSE MIT] || Java Semantic Versioning, relaxed.
|-
| [https://logging.apache.org/log4j/2.x/manual/api.html Apache Log4j API] || 2.23.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library containing Java-based logging utilities.
|-
| [https://pdfbox.apache.org/ Apache PDFBox] || 2.0.27 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Library providing utilities to create, manipulate, and extract content from PDF documents.
|-
| [https://github.com/ralfstuckert/pdfbox-layout Pdfbox2 Layout] || 1.0.1 || Runtime || MIT || Library providing PDF text layout utilities.
|-
| [https://github.com/dorkbox/Version Version] || 2.4 || Runtime || [https://opensource.org/licenses/MIT MIT] || Java library for semantic versioning.
|-
| [http://jscience.org/ JScience] || 4.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for the scientific community: units of measurement.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFX] || 11.12.7 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views.
|-
| [https://github.com/dlsc-software-consulting-gmbh/CalendarFX CalendarFXRecurrence] || 11.6.4 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating calendar views (contains the RFC 2445 support).
|-
| [https://github.com/dlsc-software-consulting-gmbh/PreferencesFX PreferencesFX] || 11.17.0 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java framework for creating a UI for application settings / preferences.
|-
| [https://github.com/FXMisc/RichTextFX/#richtextfx RichTextFX] || 0.11.2 || Runtime || [https://github.com/FXMisc/RichTextFX/blob/master/LICENSE BSD 2-Clause "Simplified" License] || Rich-text area for JavaFX.
|-
| [https://github.com/brunomnsilva/JavaFXSmartGraph/ JavaFXSmartGraph] || 0.9.4 || Runtime || [https://github.com/brunomnsilva/JavaFXSmartGraph/blob/master/LICENSE.txt MIT] || Directed-graph visualization for JavaFX.
|-
| [https://github.com/controlsfx/controlsfx ControlsFX] || 11.2.1 || Runtime || [https://github.com/controlsfx/controlsfx/blob/master/license.txt BSD 3-Clause "New" or "Revised" License] || UI controls for JavaFX.
|-
| [https://github.com/Kobee1203/schema-org-java Schema-org-java] || 0.6.0 || Runtime || [https://github.com/Kobee1203/schema-org-java/blob/main/LICENSE Apache 2.0] || Commons and serializer libraries and maven plugin generator for [https://Schema.org Schema.org] types.
|-
| [https://github.com/vatbub/mslinks FOKProjects MSLinks] || 1.0.6.2 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Java library for parsing and creating Windows shortcut files.
|-
| [https://github.com/kordamp/ikonli kordamp.ikonli] || 12.3.1 || Runtime || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Icon packs for Java applications.
|-
| [https://www.iconfinder.com/search/?q=cutting+board&iconset=food-and-cook-1 Cutting Board Icon] || || Runtime || [https://creativecommons.org/licenses/by/3.0/ Creative Common Attribution 3.0] || Icon template by Irfan Setiawan. Icon subsequently colorized by CuttingBoard application author and remains under Creative Common license.
|-
| [https://github.com/saasquatch/forge-inflector-standalone/blob/master/src/main/java/com/saasquatch/forge_inflector_standalone/Inflector.java Inflector] || || Runtime || [http://www.eclipse.org/legal/epl-v10.html Eclipse Public License version 1.0] || File containing language utilities.
|-
| [https://github.com/unicode-org/icu ICU4J] || 75.1 || Runtime || [https://github.com/unicode-org/icu/blob/main/icu4c/LICENSE Unicode® Copyright] || Set of Java libraries providing Unicode and Globalization support.
|-
| [https://fdc.nal.usda.gov/api-guide.html FoodData Central API] || 1.0.0 || REST API || [https://creativecommons.org/publicdomain/zero/1.0/ Creative Commons 0 1.0 Universal] || USDA web server API that provides query and extraction capability for food product nutrition.
|-
| [https://www.eclipse.org/ Eclipse IDE] || 2022-09 (4.25.0) || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Integrated Development Environment for Java Developers.
|-
| [https://junit.org/junit5/ JUnit Jupiter API/Engine] || 5.11.0 || Build || [https://www.eclipse.org/legal/epl-2.0/ EPL 2.0] || Testing framework for Java.
|-
| [https://maven.apache.org/ Maven] || POM version 4.0.0 || Build || [https://www.apache.org/licenses/LICENSE-2.0 Apache 2.0] || Software project management and comprehension tool.
|-
| [https://gluonhq.com/products/scene-builder SceneBuilder] || 18 || Build || [https://gluonhq.com/products/scene-builder/ 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.

{| class="wikitable"
|+ Incorporated Data Sources
|-
! Data Source !! Identification !! Copyright !! Citation
|-
| [https://fdc.nal.usda.gov/download-datasets.html 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
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dv Nutrient Recommendations: Daily Values] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://ods.od.nih.gov/HealthInformation/nutrientrecommendations.aspx#dri Nutrient Recommendations: Dietary Reference Intakes] || - || - || U.S. Office of Dietary Supplements, National Institutes of Health
|-
| [https://www.dietaryguidelines.gov/sites/default/files/2021-03/Dietary_Guidelines_for_Americans-2020-2025.pdf 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
|-
| [https://nap.nationalacademies.org/catalog/11537/dietary-reference-intakes-the-essential-guide-to-nutrient-requirements/ Dietary Reference Intakes: The Essential Guide to Nutrient Requirements] || ISBN 978-0-309-10091-5 | 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
|-
| [https://nap.nationalacademies.org/catalog/10490/dietary-reference-intakes-for-energy-carbohydrate-fiber-fat-fatty-acids-cholesterol-protein-and-amino-acids/ Dietary Reference Intakes for Energy, Carbohydrate, Fiber, Fat, Fatty Acids, Cholesterol, Protein, and Amino Acids] || ISBN 978-0-309-08537-3 | 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
|-
| [https://public-inspection.federalregister.gov/2016-11867.pdf 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
|-
| [https://www.fao.org/uploads/media/bognar_bfe-r-02-03.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400530/pdf/ah102.pdf 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
|-
| [https://www.ars.usda.gov/ARSUserFiles/80400535/Data/retn/USDA_CookingYields_MeatPoultry02.pdf 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
|-
| [https://www.langual.org/Download/RecipeCalculation/Bell%20et%20al%20-%20Report%20on%20Nutrient%20Losses%20and%20Gains%20Factors%20used%20in%20European%20Food%20Composition%20Databases.pdf 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)
|-
| [https://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ%3AL%3A2011%3A304%3A0018%3A0063%3AEN%3APDF 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
|-
| [https://www.ars.usda.gov/northeast-area/beltsville-md-bhnrc/beltsville-human-nutrition-research-center/methods-and-application-of-food-composition-laboratory/mafcl-site-pages/nutrient-retention-factors/ 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
|-
| [https://www.gov.uk/government/publications/composition-of-foods-integrated-dataset-cofid 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 Licence v3.0
|}