Write down documentation on the functionality of container stacks

3 files changed, 51 insertions, 2 deletions

diff --git a/docs/index.md b/docs/index.md
index 8ca834cb2f..0165e3d741 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -18,4 +18,4 @@ Index
 ----
 The following chapters are available in this documentation:
 * [Repositories](repositories.md): An overview of the repositories that together make up the Cura application.
-* [Profiles](profiles/profiles.md): About the profile system of Cura.
\ No newline at end of file
+* [Profiles](profiles/profiles.md): About the setting and profile system of Cura.
\ No newline at end of file
diff --git a/docs/profiles/container_stacks.md b/docs/profiles/container_stacks.md
new file mode 100644
index 0000000000..05fa5ba1d2
--- /dev/null
+++ b/docs/profiles/container_stacks.md
@@ -0,0 +1,33 @@
+Container Stacks
+====
+When the user selects the profiles and settings to print with, he can swap out a number of profiles. The profiles that are currently in use are stored in several container stacks. These container stacks always have a definition container at the bottom, which defines all available settings and all available properties for each setting. The profiles on top of that definition can then override the `value` property of some of those settings.
+
+When deriving a setting value, a container stack starts looking at the top-most profile to see if it contains an override for that setting. If it does, it returns that override. Otherwise, it looks into the second profile. If that also doesn't have an override for this setting, it looks into the third profile, and so on. The last profile is always a definition container which always contains an value for all settings. This way, the profiles at the top will always win over the profiles at the bottom. There is a clear precedence order for which profile wins over which other profile.
+
+A Machine Instance
+----
+A machine instance is a printer that the user has added to his configuration. It consists of multiple container stacks: One for global settings and one for each of the available extruders. This way, different extruders can contain different materials and quality profiles, for instance. The global stack contains a different set of profiles than the extruder stacks.
+
+While Uranium defines no specific roles for the entries in a container stack, Cura defines rigid roles for each slot in a container stack. These are the layouts for the container stacks of an example printer with 2 extruders.
+
+![Three container stacks](../resources/machine_instance.svg)
+
+To expand on this a bit further, each extruder stack contains the following profiles:
+* A user profile, where extruder-specific setting changes are stored that are not (yet) saved to a custom profile. If the user changes a setting that can be adjusted per extruder (such as infill density) then it gets stored here. If the user adjusts a setting that is global it will immediately be stored in the user profile of the global stack.
+* A custom profile. If the user saves his setting changes to a custom profile, it gets moved from the user profile to here. Actually a "custom profile" as the user sees it consists of multiple profiles: one for each extruder and one for the global settings.
+* An intent profile. The user can select between several intents for his print, such as precision, strength, visual quality, etc. This may be empty as well, which indicates the "default" intent.
+* A quality profile. The user can select between several quality levels.
+* A material profile, where the user selects which material is loaded in this extruder.
+* A nozzle profile, where the user selects which nozzle is installed in this extruder.
+* Definition changes, which stores the changes that the user made for this extruder in the Printer Settings dialogue.
+* Extruder. The user is not able to swap this out. This is a definition that lists the extruder number for this extruder and optionally things that are fixed in the printer, such as the nozzle offset.
+
+The global container stack contains the following profiles:
+* A user profile, where global setting changes are stored that are not (yet) saved to a custom profile. If the user changes for instance the layer height, the new value for the layer height gets stored here.
+* A custom profile. If the user saves his setting changes to a custom profile, the global settings that were in the global user profile get moved here.
+* An intent profile. Currently this must ALWAYS be empty. There are no global intent profiles. This is there for historical reasons.
+* A quality profile. This contains global settings that match with the quality level that the user selected. This global quality profile cannot be specific to a material or nozzle.
+* A material profile. Currently this must ALWAYS be empty. There are no global material profiles. This is there for historical reasons.
+* A variant profile. Currently this must ALWAYS be empty. There are no global variant profiles. This is there for historical reasons.
+* Definition changes, which stores the changes that the user made to the printer in the Printer Settings dialogue.
+* Printer. This specifies the currently used printer model, such as Ultimaker 3, Ultimaker S5, etc.
\ No newline at end of file
diff --git a/docs/profiles/profiles.md b/docs/profiles/profiles.md
index be9e4580b4..5428511d01 100644
--- a/docs/profiles/profiles.md
+++ b/docs/profiles/profiles.md
@@ -2,10 +2,26 @@ Profiles
 ====
 Cura's profile system is very advanced and has gotten pretty complex. This chapter is an attempt to document how it is structured.
 
+Index
+----
+The following pages describe the profile and setting system of Cura:
+* [Container Stacks](container_stacks.md): Which profiles can be swapped out and how they are ordered when evaluating a setting.
+
 Glossary
 ----
 The terminology for these profiles is not always obvious. Here is a glossary of the terms that we'll use in this chapter.
 * **Profile:** Either an *instance container* or a *definition container*.
 * **Definition container:** Profile that's stored as .def.json file, defining new settings and all of their properties. In Cura these represent printer models and extruder trains.
 * **Instance container:** Profile that's stored as .inst.cfg file or .xml.fdm_material file, which override some setting values. In Cura these represent the other profiles.
-* **[Container] Stack:** A list of profiles, with one definition container at the bottom and instance containers for the rest. All settings are defined in the definition container. The rest of the profiles each specify a set of value overrides. The profiles at the top always override the profiles at the bottom.
\ No newline at end of file
+* **[Container] stack:** A list of profiles, with one definition container at the bottom and instance containers for the rest. All settings are defined in the definition container. The rest of the profiles each specify a set of value overrides. The profiles at the top always override the profiles at the bottom.
+* **Machine instance:** An instance of a printer that the user has added. The list of all machine instances is shown in a drop-down in Cura's interface.
+* **Material:** A type of filament that's being sold by a vendor as a product.
+* **Filament spool:** A single spool of material.
+* **Quality profile:** A profile that is one of the options when the user selects which quality level they want to print with.
+* **Intent profile:** A profile that is one of the options when the user selects what his intent is.
+* **Custom profile:** A user-made profile that is stored when the user selects to "create a profile from the current settings/overrides".
+* **Quality-changes profile:** Alternative name for *custom profile*. This name is used in the code more often, but it's a bit misleading so this documentation prefers the term "custom profile".
+* **User profile:** A profile containing the settings that the user has changed, but not yet saved to a profile.
+* **Variant profile:** A profile containing some overrides that allow the user to select variants of the definition. As of this writing this is only used for the nozzles.
+* **Quality level:** A measure of quality where the user can select from, for instance "normal", "fast", "high". When selecting a quality level, Cura will select a matching quality profile for each extruder.
+* **Quality type:** Alternative name for *quality level*. This name is used in the code more often, but this documentation prefers the term "quality level".
\ No newline at end of file