+1 on confusing. A single central source of knowledge explaining Nim's current and near-future semantics is sorely needed. Right now information is spread out all over the place, and is often rather vague. A _best practices_ manual detailing how the semantics work, and how they change using different settings would be extremely useful, especially to somebody who is coming to Nim for the first time and is not well versed in how it was designed and how it has changed over the years. I'm talking specifically about anything having to do with copying and moving, deep/shallow copying, destructors, etc., and how those features interact with the GC and the ffi.
Example from shallow pragma docs: [https://nim-lang.github.io/Nim/manual.html#pragmas-shallow-pragma](https://nim-lang.github.io/Nim/manual.html#pragmas-shallow-pragma) "This can cause serious semantic issues and break memory safety! However, it can speed up assignments considerably, because the semantics of Nim require deep copying of sequences and strings. " What issues can it cause, precisely? How would one use the pragma in a safe way? Where are the semantics of nim described in detail to allow one to make these kinds of judgment calls? Where are there examples of it's correct usage? example from shallowCopy: [https://nim-lang.github.io/Nim/system.html#shallowCopy%2CT%2CT](https://nim-lang.github.io/Nim/system.html#shallowCopy%2CT%2CT) "The shallow copy only changes the semantics for sequences and strings (and types which contain those). Be careful with the changed semantics though! There is a reason why the default assignment does a deep copy of sequences and strings."' How would I be careful? What are the best practices? When would I not want to use this? What is the "reason" that assignment does a deep copy, and where is this reason described?
