cleanup, docs

site/doc/pages/path_real.txt

@@ -2,15 +2,18 @@
 String path_real(String path)
 
 :params
-path : filesystem path
-return value : canonical absolute path, or an empty string when the path cannot be resolved
+path : path to resolve
+return value : the canonical absolute path, or "" if it cannot be resolved
+
+:content
+Resolves a path to its canonical absolute form, following symlinks and collapsing `.` and `..` segments. The path must exist. Combine with `path_is_within()` to validate that user-supplied paths stay inside an allowed root.
+
+:example
+file_put_contents("/tmp/doc-real.txt", "x");
+print(path_real("/tmp/../tmp/./doc-real.txt"), "\n");
 
 :see
 >sys
->path_is_within
-
-:content
-Returns the host canonical path using `realpath()`. Relative paths resolve according to the worker process current directory.
-
-:example
-print("path_real example\n");
+path_is_within
+expand_path
+file_symlink