Warning, /utilities/kookbook/doc/intro.md is written in an unsupported language. File is not indexed.

0001 # KookBook
0002 
0003 A simple recipe manager taking structured markdown for recipes.
0004 
0005 ## A cookbook
0006 
0007 A cookbook, or collection of recipes, is a folder structure containing one or more recipes with markdown files and named *.recipe.md. The folder structure can be used as one way to browse and group the recipes.
0008 See the file format section for details on the file format.
0009 
0010 Recipes can be synced with others using external tools like git repositories, nextcloud or many other services.
0011 
0012 ## The desktop application
0013 
0014 The application consists of a set of panes. Some are for helping finding recipes in different ways, and others are for help recipe writers figuring out how it is parsed.
0015 
0016 Right clicking on the top level toolbar let you hide and show panes.
0017 
0018 The top level toolbar contains some actions.
0019 
0020  * Open sets the root folder for the recipe collection, or cookbook.
0021  * Edit launches the system editor to let you edit the selected recipe.
0022  * New recipe creates a recipe from template and launches a system editor for editing the recipe.
0023  * Refresh reloads the entire recipe collection. A edited recipe is refreshed upon save, but if external tools have added or removed files, refresh is not automatic.
0024  * Print and Print preview allows printing
0025 
0026 
0027 ### Main pane
0028 The central one displays the recipe, or if no recipe is selected, this document.
0029 
0030 ### Recipe pane
0031 The recipes ordered as how they are laid out on the file system in the selected folder and sub folders. Only files ending with recipe.md is parsed.
0032 
0033 ### Tags pane
0034 The tags pane shows the recipes indexed by their tags
0035 
0036 ### Ingredients pane
0037 The recipes indexed by their ingredients. This is for example for helping figure out how to use a surplus of bell peppers.
0038 
0039 ### Title pane
0040 All recipes by title. Search is available.
0041 
0042 ### Raw view pane
0043 The raw markdown file. Mostly for recipe writers.
0044 
0045 ### Meta data pane
0046 The data extracted from the recipe. Mostly for recipe writers.
0047 
0048 ## File Format
0049 
0050 The full recipe is rendered as markdown, and some specific pieces of information is parsed from it in a structured way. The file type is .recipe.md
0051 
0052 All in all, 3 groups of data are read. Title, Ingredients and Metadata, and are read in that order.
0053 
0054 Title is the first top level header, like
0055 
0056     # Fancy salad
0057 is parsed as "Fancy salad" as the title.
0058 
0059 The parser is supposed to ignore anything until reaching a line starting with
0060 
0061     ### Ingred
0062 and at this point switch to ingredients parsing. More on that later. Ingredients parsing stops at a line starting with
0063 
0064     ### Direc
0065 and ignores any lines until a line starting with
0066 
0067     ### Meta
0068 The meta section is a set of lines with specific syntax:
0069 
0070     key: value
0071 More on meta data parsing later.
0072 A key can be repeated and is concatenated.
0073 
0074 
0075 #### Ingredients parsing
0076 
0077 Ingredients lines for parsing needs to be structured as a bullet list like
0078 
0079      * amount unit ingredient name, some additional information
0080 
0081 and is parsed by ignoring the asterisk, the first two words, and whatever is after a comma.
0082 
0083 An ingredient list like
0084 
0085      * 1 kg flour
0086      * 2 pcs red bell pepper, alternatively yellow bell pepper
0087 
0088 will get the parsed ingredient list for indexing and other purposes as
0089 
0090     flour
0091     red bell pepper
0092 
0093 
0094 Ingredients without an amount, e.g.
0095 
0096      * salt
0097      * pepper
0098 
0099 Will not show up in ingredient indexing.
0100 
0101 
0102 #### Metadata parsing
0103 
0104 so far, only tags as key is parsed specifically as comma separated list like
0105 
0106     tags: kid friendly, vegetarian
0107 
0108 is parsed into the tags
0109  * kid friendly
0110  * vegetarian
0111 
0112 An author tag can only contain one value, but it can be repeated.
0113 
0114     author: John Doe
0115     author: Jane Doe
0116 
0117 
0118 Other tags with specific parsing rules might come in the future
0119 
0120 
0121 
0122 ## About
0123 
0124 Kookbook is made by Sune Vuorela <sune@kde.org> and is available under the MIT/X11 license (see license).
0125 
0126 Kookbook uses the Qt Toolkit <http://qt.io> for UI and file access functionality, and uses the markdown library Discount <https://github.com/Orc/discount>
0127 
0128 
0129 ## License
0130 
0131     Copyright (c) 2018 Sune Vuorela <sune@vuorela.dk>
0132 
0133     Permission is hereby granted, free of charge, to any person
0134     obtaining a copy of this software and associated documentation
0135     files (the "Software"), to deal in the Software without
0136     restriction, including without limitation the rights to use,
0137     copy, modify, merge, publish, distribute, sublicense, and/or sell
0138     copies of the Software, and to permit persons to whom the
0139     Software is furnished to do so, subject to the following
0140     conditions:
0141 
0142     The above copyright notice and this permission notice shall be
0143     included in all copies or substantial portions of the Software.
0144 
0145     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
0146     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
0147     OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
0148     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
0149     HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
0150     WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
0151     FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
0152     OTHER DEALINGS IN THE SOFTWARE.
0153 
0154