Explain where .so paths are rooted, and why, and discourage its use;

feedback and ok jmc@, suggested by and ok kristaps@.

1 files changed, 16 insertions, 0 deletions

diff --git a/roff.7 b/roff.7
index 89f20425..d07349ed 100644
--- a/roff.7
+++ b/roff.7
@@ -844,6 +844,22 @@ only accepts relative paths not containing the strings
 .Qq ../
 and
 .Qq /.. .
+.Pp
+This request requires
+.Xr man 1
+to change to the right directory before calling
+.Xr mandoc 1 ,
+per convention to the root of the manual tree.
+Typical usage looks like:
+.Pp
+.Dl \&.so man3/Xcursor.3
+.Pp
+As the whole concept is rather fragile, the use of
+.Sx \&so
+is discouraged.
+Use
+.Xr ln 1
+instead.
 .Ss \&ta
 Set tab stops.
 This line-scoped request can take an arbitrary number of arguments.