docs(user): improve documentation on promoted attributes

docs/User Guide/User Guide/Advanced Usage/Attributes.md

@@ -12,19 +12,30 @@ In Trilium, attributes are key-value pairs assigned to notes, providing addition
 
 These attributes play a crucial role in organizing, categorizing, and enhancing the functionality of notes.
 
+## Types of attributes
+
+Conceptually there are two types of attributes (applying to both labels and relations):
+
+1.  **System attributes**  
+    As the name suggest, these attributes have a special meaning since they are interpreted by Trilium. For example the `color` attribute will change the color of the note as displayed in the <a class="reference-link" href="../Basic%20Concepts%20and%20Features/UI%20Elements/Note%20Tree.md">Note Tree</a> and links, and `iconClass` will change the icon of a note.
+2.  **User-defined attributes**  
+    These are free-form labels or relations that can be used by the user. They can be used purely for categorization purposes (especially if combined with <a class="reference-link" href="../Basic%20Concepts%20and%20Features/Navigation/Search.md">Search</a>), or they can be given meaning through the use of <a class="reference-link" href="../Scripting.md">Scripting</a>.
+
+In practice, Trilium makes no direct distinction of whether an attribute is a system one or a user-defined one. A label or relation is considered a system attribute if it matches one of the built-in names (e.g. like the aforementioned `iconClass`). Keep this in mind when creating  <a class="reference-link" href="Attributes/Promoted%20Attributes.md">Promoted Attributes</a> in order not to accidentally alter a system attribute (unless intended).
+
 ## Viewing the list of attributes
 
 Both the labels and relations for the current note are displayed in the _Owned Attributes_ section of the <a class="reference-link" href="../Basic%20Concepts%20and%20Features/UI%20Elements/Ribbon.md">Ribbon</a>, where they can be viewed and edited. Inherited attributes are displayed in the _Inherited Attributes_ section of the ribbon, where they can only be viewed.
 
 In the list of attributes, labels are prefixed with the `#` character whereas relations are prefixed with the `~` character.
 
-## Multiplicity
-
-Attributes in Trilium can be "multi-valued", meaning multiple attributes with the same name can co-exist.
-
 ## Attribute Definitions and Promoted Attributes
 
-Special labels create "label/attribute" definitions, enhancing the organization and management of attributes. For more details, see <a class="reference-link" href="Attributes/Promoted%20Attributes.md">Promoted Attributes</a>.
+<a class="reference-link" href="Attributes/Promoted%20Attributes.md">Promoted Attributes</a> create a form-like editing experience for attributes, which makes it easy to enhancing the organization and management of attributes
+
+## Multiplicity
+
+Attributes in Trilium can be "multi-valued", meaning multiple attributes with the same name can co-exist. This can be combined with <a class="reference-link" href="Attributes/Promoted%20Attributes.md">Promoted Attributes</a> to easily add them.
 
 ## Attribute Inheritance
 

docs/User Guide/User Guide/Advanced Usage/Attributes/Promoted Attributes.md

@@ -1,31 +1,74 @@
 # Promoted Attributes
-Promoted attributes are [attributes](../Attributes.md) which are considered important and thus are "promoted" onto the main note UI. See example below:
+<figure class="image image_resized" style="width:61.4%;"><img style="aspect-ratio:938/368;" src="Promoted Attributes_image.png" width="938" height="368"></figure>
 
-![](Promoted%20Attributes_promot.png)
+Promoted attributes are [attributes](../Attributes.md) which are displayed prominently in the UI which allow them to be easily viewed and edited.
 
-You can see the note having kind of form with several fields. Each of these is just regular attribute, the only difference is that they appear on the note itself.
+One way of seeing promoted attributes is as a kind of form with several fields. Each field is just regular attribute, the only difference is that they appear on the note itself.
 
 Attributes can be pretty useful since they allow for querying and script automation etc. but they are also inconveniently hidden. This allows you to select few of the important ones and push them to the front of the user.
 
-Now, how do we make attribute to appear on the UI?
-
 ## Attribute definition
 
-Attribute is always name-value pair where both name and value are strings.
+In order to have promoted attributes, there needs to be a way to define them.
 
-_Attribute definition_ specifies how should this value be interpreted - is it just string, or is it a date? Should we allow multiple values or note? And importantly, should we _promote_ the attribute or not?
+<figure class="image image-style-align-right image_resized" style="width:38.82%;"><img style="aspect-ratio:492/346;" src="1_Promoted Attributes_image.png" width="492" height="346"></figure>
 
-![](Promoted%20Attributes_image.png)
+Technically, attributes are only name-value pairs where both name and value are strings.
 
-You can notice tag attribute definition. These "definition" attributes define how the "value" attributes should behave.
+The _Attribute definition_ specifies how should this value be interpreted:
 
-So there's one attribute for value and one for definition. But notice how definition attribute is [Inheritable](Attribute%20Inheritance.md), meaning that it's also applied to all descendant note. So in a way, this definition is used for the whole subtree while "value" attributes are applied only for this note.
+*   Is it just string, or is it a date?
+*   Should we allow multiple values or note?
+*   Should we _promote_ the attribute or not?
+
+## Creating a new promoted attribute definition
+
+To create a new promoted attribute:
+
+1.  Go to a note.
+2.  Go to _Owned Attributes_ in the <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Ribbon.md">Ribbon</a>.
+3.  Press the + button.
+4.  Select either _Add new label definition_ or _Add new relation definition_.
+5.  Select the name which will be name of the label or relation that will be created when the promoted attribute is edited.
+6.  Ensure _Promoted_ is checked in order to display it at the top of notes.
+7.  Optionally, choose an _Alias_ which will be displayed next to the promoted attribute instead of the attribute name. Generally it's best to choose a “user-friendly” name since it can contain spaces and other characters which are not supported as attribute names.
+8.  Check _Inheritable_ to apply it to this note and all its descendants. To keep it only for the current note, un-check it.
+9.  Press “Save & Close” to apply the changes.
+
+## How attribute definitions actually work
+
+When a new promoted attribute definition is created, it creates a corresponding label prefixed with either `label` or `relation`, depending on the definition type:
+
+```
+#label:myColor(inheritable)="promoted,alias=Color,multi,color"
+```
+
+The only purpose of the attribute definition is to set up a template. If the attribute was marked as promoted, then it's also displayed to the user for easy editing.
+
+|     |     |
+| --- | --- |
+| <figure class="image"><img style="aspect-ratio:495/157;" src="2_Promoted Attributes_image.png" width="495" height="157"></figure> | Notice how the promoted attribute definition only creates a “Due date” box above the text content. |
+| <figure class="image"><img style="aspect-ratio:663/160;" src="3_Promoted Attributes_image.png" width="663" height="160"></figure> | Once a value is set by the user, a new label (or relation, depending on the type) is created. The name of the attribute matches one set when creating the promoted attribute. |
+
+So there's one attribute for value and one for definition. But notice how an definition attribute can be made [Inheritable](Attribute%20Inheritance.md), meaning that it's also applied to all descendant notes. In this case, the definition used for the whole sub-tree while "value" attributes are for each not individually.
+
+## Using system attributes
+
+It's possible to create promoted attributes out of system attributes, to be able to easily alter them.
+
+Here are a few practical examples:
+
+*   <a class="reference-link" href="../../Collections.md">Collections</a> already make use of this practice, for example:
+    *   Calendars add “Start Date”, “End Date”, “Start Time” and “End Time” as promoted attributes. These map to system attributes such as `startDate` which are then interpreted by the calendar view.
+    *   <a class="reference-link" href="../../Collections/Presentation.md">Presentation</a> adds a “Background” promoted attribute for each of the slide to easily be able to customize.
+*   The Trilium documentation (which is edited in Trilium) uses a promoted attribute to be able to easily edit the `#shareAlias` (see <a class="reference-link" href="../Sharing.md">Sharing</a>) in order to form clean URLs.
+*   If you always edit a particular system attribute such as `#color`, simply create a promoted attribute for it to make it easier.
 
 ### Inverse relation
 
 Some relations always occur in pairs - my favorite example is on the family. If you have a note representing husband and note representing wife, then there might be a relation between those two of `isPartnerOf`. This is bidirectional relationship - meaning that if a relation is pointing from husband to wife then there should be always another relation pointing from wife to husband.
 
-Another example is with parent - child relationship. Again these always occur in pairs, but in this case it's not exact same relation - the one going from parent to child might be called `isParentOf` and the other one going from child to parent might be called `isChildOf`.
+Another example is with parent-child relationship. Again these always occur in pairs, but in this case it's not exact same relation - the one going from parent to child might be called `isParentOf` and the other one going from child to parent might be called `isChildOf`.
 
 Relation definition allows you to specify such "inverse relation" - for the relation you just define you specify which is the inverse relation. Note that in the second example we should have two relation definitions - one for `isParentOf` which defines `isChildOf` as inverse relation and then second relation definition for `isChildOf` which defines `isParentOf` as inverse relation.