docgen: mangling using _. instead of @@ to avoid issue (#14454)

compiler/nimpaths.nim

@@ -27,6 +27,9 @@ const
   nimdocOutCss* = "nimdoc.out.css"
     # `out` to make it easier to use with gitignore in user's repos
   htmldocsDirname* = "htmldocs"
+  dotdotMangle* = "_._"  ## refs #13223
+    # if this changes, make sure it's consistent with `esc` and `escapeLink`
+    # lots of other obvious options won't work, see #14454; `_` could work too
 
 proc interp*(path: string, nimr: string): string =
   result = path % ["nimr", nimr]

lib/packages/docutils/rstgen.nim

@@ -28,6 +28,8 @@
 import strutils, os, hashes, strtabs, rstast, rst, highlite, tables, sequtils,
   algorithm, parseutils
 
+import "$lib/../compiler/nimpaths"
+
 const
   HtmlExt = "html"
   IndexExt* = ".idx"
@@ -78,8 +80,6 @@ type
     testCmd: string
     status: int
 
-const dotdotMangle* = "@@"  ## refs #13223
-
 proc prettyLink*(file: string): string =
   changeFileExt(file, "").replace(dotdotMangle, "..")
 

testament/lib/stdtest/specialpaths.nim

@@ -1,6 +1,15 @@
 #[
 todo: move findNimStdLibCompileTime, findNimStdLib here
 xxx: consider moving this to $nim/compiler/relpaths.nim to get relocatable paths
+
+## note: $lib vs $nim
+note: these can resolve to 3 different paths if running via `nim c --lib:lib foo`,
+eg if compiler was installed via nimble (or is in nim path), and nim is external
+(ie not in `$lib/../bin/` dir)
+
+import "$lib/../compiler/nimpaths" # <- most robust if you want to favor --lib:lib
+import "$nim/compiler/nimpaths"
+import compiler/nimpaths
 ]#
 
 import os

tests/misc/trunner.nim

@@ -12,7 +12,7 @@ from std/sequtils import toSeq,mapIt
 from std/algorithm import sorted
 import stdtest/[specialpaths, unittest_light]
 
-import "$nim/compiler/nimpaths"
+import "$lib/../compiler/nimpaths"
 
 const
   nim = getCurrentCompilerExe()
@@ -101,21 +101,21 @@ else: # don't run twice the same test
       of 0,5:
         let htmlFile = htmldocsDir/"mmain.html"
         check htmlFile in outp # sanity check for `hintSuccessX`
-        assertEquals ret, """
-@@/imp.html
-@@/imp.idx
-dochack.js
+        assertEquals ret, fmt"""
+{dotdotMangle}/imp.html
+{dotdotMangle}/imp.idx
+{docHackJsFname}
 imp.html
 imp.idx
 imp2.html
 imp2.idx
 mmain.html
 mmain.idx
-nimdoc.out.css
-theindex.html""", context
-      of 1: assertEquals ret, """
-dochack.js
-nimdoc.out.css
+{nimdocOutCss}
+{theindexFname}""", context
+      of 1: assertEquals ret, fmt"""
+{docHackJsFname}
+{nimdocOutCss}
 tests/nimdoc/imp.html
 tests/nimdoc/imp.idx
 tests/nimdoc/sub/imp.html
@@ -124,20 +124,20 @@ tests/nimdoc/sub/imp2.html
 tests/nimdoc/sub/imp2.idx
 tests/nimdoc/sub/mmain.html
 tests/nimdoc/sub/mmain.idx
-theindex.html"""
-      of 2, 3: assertEquals ret, """
-dochack.js
+{theindexFname}"""
+      of 2, 3: assertEquals ret, fmt"""
+{docHackJsFname}
 mmain.html
 mmain.idx
-nimdoc.out.css""", context
-      of 4: assertEquals ret, """
-dochack.js
-nimdoc.out.css
+{nimdocOutCss}""", context
+      of 4: assertEquals ret, fmt"""
+{docHackJsFname}
+{nimdocOutCss}
 sub/mmain.html
 sub/mmain.idx""", context
-      of 6: assertEquals ret, """
+      of 6: assertEquals ret, fmt"""
 mmain.html
-nimdoc.out.css""", context
+{nimdocOutCss}""", context
       else: doAssert false
 
   block: # mstatic_assert