feat: clarify %dir and add illegal char guideline

Signed-off-by: Owen-sz <[email protected]>

Author: Owen-sz

content/docs/rpm/sections.mdx

@@ -324,7 +324,7 @@ The following is an exhaustive list of file attributes available:
 # - config(missingok)
 # - config(noreplace)
 %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

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 UPSTREAM-VERSION
+%global sanitized_ver %(echo %{ver} | sed 's/-//g')
+...
+Version:  %sanitized_ver # This will expand to UPSTREAMVERSION 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).