document since (#17048)

* document `since`
* address comment

compiler/commands.nim

@@ -940,8 +940,6 @@ proc processSwitch*(switch, arg: string, pass: TCmdLinePass, info: TLineInfo;
     of "1.0":
       defineSymbol(conf.symbols, "NimMajor", "1")
       defineSymbol(conf.symbols, "NimMinor", "0")
-      # always be compatible with 1.0.100:
-      defineSymbol(conf.symbols, "NimPatch", "100")
       # old behaviors go here:
       defineSymbol(conf.symbols, "nimOldRelativePathBehavior")
       undefSymbol(conf.symbols, "nimDoesntTrackDefects")
@@ -950,11 +948,11 @@ proc processSwitch*(switch, arg: string, pass: TCmdLinePass, info: TLineInfo;
     of "1.2":
       defineSymbol(conf.symbols, "NimMajor", "1")
       defineSymbol(conf.symbols, "NimMinor", "2")
-      # always be compatible with 1.2.100:
-      defineSymbol(conf.symbols, "NimPatch", "100")
       conf.globalOptions.incl optNimV12Emulation
     else:
-      localError(conf, info, "unknown Nim version; currently supported values are: {1.0}")
+      localError(conf, info, "unknown Nim version; currently supported values are: `1.0`, `1.2`")
+    # always be compatible with 1.x.100:
+    defineSymbol(conf.symbols, "NimPatch", "100")
   of "benchmarkvm":
     processOnOffSwitchG(conf, {optBenchmarkVM}, arg, pass, info)
   of "profilevm":

doc/advopt.txt

@@ -146,7 +146,7 @@ Advanced options:
                             enable experimental language feature
   --legacy:$2
                             enable obsolete/legacy language feature
-  --useVersion:1.0          emulate Nim version X of the Nim compiler
+  --useVersion:1.0|1.2      emulate Nim version X of the Nim compiler, for testing
   --profiler:on|off         enable profiling; requires `import nimprof`, and
                             works better with `--stackTrace:on`
                             see also https://nim-lang.github.io/Nim/estp.html

lib/std/private/since.nim

@@ -1,3 +1,17 @@
+##[
+`since` is used to emulate older versions of nim stdlib with `--useVersion`,
+see `tuse_version.nim`.
+
+If a symbol `foo` is added in version `(1,3,5)`, use `{.since: (1.3.5).}`, not
+`{.since: (1.4).}`, so that it works in devel in between releases.
+
+The emulation cannot be 100% faithful and to avoid adding too much complexity,
+`since` is not needed in those cases:
+* if a new module is added
+* if an overload is added
+* if an extra parameter to an existing routine is added
+]##
+
 template since*(version: (int, int), body: untyped) {.dirty.} =
   ## Evaluates `body` if the ``(NimMajor, NimMinor)`` is greater than
   ## or equal to `version`. Usage:
@@ -16,4 +30,4 @@ template since*(version: (int, int, int), body: untyped) {.dirty.} =
   ##   proc fun*() {.since: (1, 3, 1).}
   ##   since (1, 3, 1): fun()
   when (NimMajor, NimMinor, NimPatch) >= version:
-    body
+    body