From 3260489fd37b43b0348813a4e308eef91a8b83b0 Mon Sep 17 00:00:00 2001 From: Joel Dueck Date: Tue, 8 Dec 2020 17:19:00 -0600 Subject: [PATCH] Clarify use of build-path/convention-type in scribble docs (fixes #3424) I constructed this PR using GitHub's edit feature, so the commit has not been tested. --- pkgs/racket-doc/scribblings/reference/paths.scrbl | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/pkgs/racket-doc/scribblings/reference/paths.scrbl b/pkgs/racket-doc/scribblings/reference/paths.scrbl index adbfc52e35..a1e891ad86 100644 --- a/pkgs/racket-doc/scribblings/reference/paths.scrbl +++ b/pkgs/racket-doc/scribblings/reference/paths.scrbl @@ -302,7 +302,20 @@ Windows examples. path-for-some-system?]{ Like @racket[build-path], except a path convention type is specified -explicitly.} +explicitly. + +Note that, just as with @racket[build-path], any string arguments for either +@racket[base] or @racket[sub] will be implicitly converted into a path for the +current platform before being combined with the others. For this reason, you +cannot use this function to build paths from strings for any platform other +than the current one; in such attempts, @racket[type] does not match the +inferred convention type for the strings and an @exnraise[exn:fail:contract]. +(To create paths for foreign platforms, see @racket[bytes->path].) + +The usefulness of @racket[build-path/convention-type] over @racket[build-path] +is limited to cases where the sub-paths contain @racket['same] or @racket['up] +elements.} + @defproc[(absolute-path? [path (or/c path? string? path-for-some-system?)]) boolean?]{