diff --git a/doc/manual.md b/doc/manual.md
index f5ee10fda3..c381ab4100 100644
--- a/doc/manual.md
+++ b/doc/manual.md
@@ -6676,6 +6676,8 @@ even when one version does not export some of these identifiers.
 
 The `import` statement is only allowed at the top level.
 
+String literals can be used for import/include statements.
+The compiler performs [path substitution](nimc.html#compiler-usage-commandminusline-switches) when used.
 
 Include statement
 -----------------
diff --git a/doc/nimc.md b/doc/nimc.md
index d367c66200..4f715ee83a 100644
--- a/doc/nimc.md
+++ b/doc/nimc.md
@@ -32,6 +32,17 @@ Compiler Usage
 
 Command-line switches
 ---------------------
+All options that take a `PATH` or `DIR` argument are subject to path substitution:
+
+- `$nim`: The global nim prefix path
+- `$lib`: The stdlib path
+- `$home` and `~`: The user's home path
+- `$config`: The directory of the module currently being compiled
+- `$projectname`: The project file's name without file extension
+- `$projectpath` and `$projectdir`: The project file's path
+- `$nimcache`: The nimcache path
+
+
 Basic command-line switches are:
 
 .. no syntax highlighting in the below included files at the moment
diff --git a/lib/system/nimscript.nim b/lib/system/nimscript.nim
index 0b49ea2e74..9ce475e5b1 100644
--- a/lib/system/nimscript.nim
+++ b/lib/system/nimscript.nim
@@ -86,6 +86,7 @@ proc patchFile*(package, filename, replacement: string) =
   ## is interpreted to be local to the Nimscript file that contains
   ## the call to `patchFile`, Nim's `--path` is not used at all
   ## to resolve the filename!
+  ## The compiler also performs `path substitution <nimc.html#compiler-usage-commandminusline-switches>`_ on `replacement`.
   ##
   ## Example:
   ##