1# KookBook
2
3A simple recipe manager taking structured markdown for recipes.
4
5## A cookbook
6
7A 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.
8See the file format section for details on the file format.
9
10Recipes can be synced with others using external tools like git repositories, nextcloud or many other services.
11
12## The desktop application
13
14The 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.
15
16Right clicking on the top level toolbar let you hide and show panes.
17
18The top level toolbar contains some actions.
19 * Open sets the root folder for the recipe collection, or cookbook.
20 * Edit launches the system editor to let you edit the selected recipe.
21 * New recipe creates a recipe from template and launches a system editor for editing the recipe.
22 * 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.
23 * Print and Print preview allows printing
24
25
26### Main pane
27The central one displays the recipe, or if no recipe is selected, this document.
28
29### Recipe pane
30The 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.
31
32### Tags pane
33The tags pane shows the recipes indexed by their tags
34
35### Ingredients pane
36The recipes indexed by their ingredients. This is for example for helping figure out how to use a surplus of bell peppers.
37
38### Title pane
39All recipes by title. Search is available.
40
41### Raw view pane
42The raw markdown file. Mostly for recipe writers.
43
44### Meta data pane
45The data extracted from the recipe. Mostly for recipe writers.
46
47## File Format
48
49The 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
50
51All in all, 3 groups of data are read. Title, Ingredients and Metadata, and are read in that order.
52
53Title is the first top level header, like
54
55    # Fancy salad
56is parsed as "Fancy salad" as the title.
57
58The parser is supposed to ignore anything until reaching a line starting with
59
60    ### Ingred
61and at this point switch to ingredients parsing. More on that later. Ingredients parsing stops at a line starting with
62
63    ### Direc
64and ignores any lines until a line starting with
65
66    ### Meta
67The meta section is a set of lines with specific syntax:
68
69    key: value
70More on meta data parsing later.
71A key can be repeated and is concatenated.
72
73
74#### Ingredients parsing
75
76Ingredients lines for parsing needs to be structured as a bullet list like
77
78     * amount unit ingredient name, some additional information
79
80and is parsed by ignoring the asterisk, the first two words, and whatever is after a comma.
81
82An ingredient list like
83
84     * 1 kg flour
85     * 2 pcs red bell pepper, alternatively yellow bell pepper
86
87will get the parsed ingredient list for indexing and other purposes as
88
89    flour
90    red bell pepper
91
92
93Ingredients without an amount, e.g.
94
95     * salt
96     * pepper
97
98Will not show up in ingredient indexing.
99
100
101#### Metadata parsing
102
103so far, only tags as key is parsed specifically as comma separated list like
104
105    tags: kid friendly, vegetarian
106
107is parsed into the tags
108 * kid friendly
109 * vegetarian
110
111An author tag can only contain one value, but it can be repeated.
112
113    author: John Doe
114    author: Jane Doe
115
116
117Other tags with specific parsing rules might come in the future
118
119
120
121## About
122
123Kookbook is made by Sune Vuorela <sune@kde.org> and is available under the MIT/X11 license (see license).
124
125Kookbook uses the Qt Toolkit <http://qt.io> for UI and file access functionality, and uses the markdown library Discount <https://github.com/Orc/discount>
126
127
128## License
129
130    Copyright (c) 2018 Sune Vuorela <sune@vuorela.dk>
131
132    Permission is hereby granted, free of charge, to any person
133    obtaining a copy of this software and associated documentation
134    files (the "Software"), to deal in the Software without
135    restriction, including without limitation the rights to use,
136    copy, modify, merge, publish, distribute, sublicense, and/or sell
137    copies of the Software, and to permit persons to whom the
138    Software is furnished to do so, subject to the following
139    conditions:
140
141    The above copyright notice and this permission notice shall be
142    included in all copies or substantial portions of the Software.
143
144    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
145    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
146    OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
147    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
148    HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
149    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
150    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
151    OTHER DEALINGS IN THE SOFTWARE.
152
153
154