feat: clarify File derivatives and add illegal char guideline

content/docs/rpm/sections.mdx

@@ -311,7 +311,7 @@ Alternatively, disable `debuginfo` and `debugsource` packages by:
 
 Files can be specified with globs (`*` and `?`).
 
-### File derivatives
+### File Derivatives
 
 Files can be specified with optionally an attribute[^3] (aka. a file directive[^4]).
 The following is an exhaustive list of file attributes available:
@@ -320,15 +320,13 @@ The following is an exhaustive list of file attributes available:
 %artifact …
 # ╰─ mado: personally never seen this used
 %config(…) …
-# ╰─ exhaustive list:
-# - config(missingok)
-# - config(noreplace)
+# ╰─ flag the specified file as being a configuration file. RPM performs additional processing for config files when packages are erased, and during installations and upgrades.
 %dir …
-# ╰─ specify a directory the package owns
+# ╰─ specify a directory the package owns if the files in that directory are not to be owned by the package
 %doc …
 # ╰─ store the file into %{_docdir}
 %docdir
-# ╰─ mado: personally never seen this used
+# ╰─ Define a directory as a documentation-only directory. Can be used when a package defines its own documentation folder and contains a large number of doc files.
 %ghost …
 # ╰─ mark a file as owned by the package, but don't actually install the file
 %license …

content/docs/terra/guidelines.mdx

@@ -409,6 +409,28 @@ It is also acceptable to add more to previous changelogs (for example, adding mi
 - If you are unsure if a bump is needed, bump it.
 - Follow appropriate changelog procedures outlined in the above section.
 
+#### Illegal Char in Version String
+
+In the case of an 'illegal character' in a `Version:{:rpmspec}` tag (such as a `-` or `/`), you will need to define a `%sanitized_ver:{:rpmspec}` macro.
+To do this, add the following lines to your spec file (assuming a `-` is used in the upstream version):
+
+```rpmspec
+%global ver 2005-05-14
+%global sanitized_ver %(echo %{ver} | sed 's/-//g')
+...
+Version: %sanitized_ver # This will expand to 20250514 in this example
+```
+
+Then, the `update.rhai` needs to be appended to replace the globaly defined `ver` instead of the usual `Version` tag.
+Your `update.rhai` should look like this:
+
+```rhai
+rpm.global("ver", gh("upstream/project")); // Remember to change the update function to what your upstream is hosted on, for example, `pypi()` or `hackage()`.
+```
+
+If a different illegal character is used, you will need to write a `sed` script to remove this character.
+More information on writing these scripts can be found [here](https://linux.die.net/man/1/sed).
+
 #### Patches
 
 - Packages SHOULD apply patches (usually via the `-p*` flag) in `%autosetup{:rpmspec}`. If this is not possible (typically when `%autosetup{:rpmspec}` is not used), you SHOULD use [%autopatch](../rpm/macros#autopatch).