docs: move not nil to the experimental page

[roryokane]

When I heard that this feature existed, and found the 2018 changelog entry that said not nil was made experimental, I looked for not nil documentation in https://nim-lang.org/docs/manual_experimental.html. When I didn’t find it there, I initially assumed the feature had no documentation. This change moves the documentation to where readers will expect it.

As well as moving the text to another file, I added instructions for enabling the experimental feature and tweaked some wording.

I tested this changed markup in a ReStructured Text editor and it looked mostly good, but I couldn’t confirm that the .. code-block:: nim will render correctly since that’s a custom block type defined by this project.

[roryokane]

Note to self: this change will affect the URL added to the D/Nim comparison table in timotheecour/D_vs_nim#36. So update that PR or make a new PR in that project after this is merged.

[timotheecour]

I tested this changed markup in a ReStructured Text editor and it looked mostly good, but I couldn’t confirm that the .. code-block:: nim will render correctly since that’s a custom block type defined by this project.

nim rst2html foo.rst or for whole docs you can ./koch docs

[timotheecour]

except it doesn't.... so I'd reword for honesty as:

# and also this:
=>
# but not yet this:

when true:
  {.experimental: "notnil"}

  type
    TObj = object
    PObject = ref TObj not nil
    TProc = (proc (x, y: int)) not nil

  proc p(x: PObject) =
    echo "not nil"
    echo x == nil

  # compiler catches this:
  # p(nil)

  # and also this:
  var x: PObject
  p(x)

prints:

not nil
true

maybe you could pull up some other compelling example from #13808 /cc @zah

[timotheecour]

add TObj = object (basically make sure it compiles )

[metagn]

Can also move for loop macros and code reordering.

[Araq]

This PR at least improves the situation, merging.