catch up on documentation for some library changes

The library changes were made as part of the package reoganization.

pkgs/racket-pkgs/racket-doc/file/scribblings/tar.scrbl

@@ -7,9 +7,12 @@
 utilities to create archive files in USTAR format, like the archive
 that the Unix utility @exec{pax} generates.  The USTAR format imposes
 limits on path lengths.  The resulting archives contain only
-directories and files (symbolic links are followed), and owner
+directories, files, and symbolic links, and owner
 information is not preserved; the owner that is stored in the archive
-is always ``root.''}
+is always ``root.''
+
+Symbolic links (on Unix and Mac OS X) are not followed, and the path
+in a link must be less than 100 bytes.}
 
 @defproc[(tar [tar-file path-string?][path path-string?] ...) 
          exact-nonnegative-integer?]{

pkgs/racket-pkgs/racket-doc/pkg/scribblings/lib.scrbl

@@ -156,7 +156,7 @@ Implements the @racket[create] command.
 Unless @racket[quiet?] is true, information about the output is repotred to the current output port.}
 
 
-@defproc[(pkg-install      [names (listof string?)]
+@defproc[(pkg-install      [descs (listof pkg-desc?)]
                            [#:dep-behavior dep-behavior
                                            (or/c #f 'fail 'force 'search-ask 'search-auto)
                                            #f]
@@ -291,16 +291,21 @@ same form as from @racket[get-all-pkg-details-from-catalogs].}
 
 
 @defproc[(pkg-single-collection [dir path-string?]
-                                [#:namespace ns namespace? (make-base-namespapce)])
+                                [#:name name string? @elem{... from @racket[dir] ...}]
+                                [#:namespace namespace namespace? (make-base-namespapce)])
          (or/c #f string?)]{
 
-Returns @racket[#f] if @racket[dir] represents a @tech{multi-collection package},
+Returns a string for a collection name if @racket[dir] represents a
-and returns a string for the collection contained by the package if @racket[dir]
+@tech{single-collection package}, or returns @racket[#f] if @racket[dir]
-represents a @tech{single-collection package}.
+represents a @tech{multi-collection package}.
 
-Detecting a @tech{single-collection package} may involve loading an
+For some single-collection packages, the package's single collection
-@filepath{info.rkt} file via @racket[getinfo/full], in which case
+is the package name; if the package name is different from the
-@racket[namespace] is used.}
+directory name, supply @racket[name].
+
+Determining a single-collection package's collection name may require
+loading an @filepath{info.rkt} file, in which case @racket[namespace]
+is passed on to @racket[get-info/full].}
 
 
 @defproc[(get-pkg-content [desc pkg-desc?]

pkgs/racket-pkgs/racket-doc/pkg/scribblings/pkg.scrbl

@@ -306,8 +306,10 @@ sub-sub-commands:
 
   @item{@DFlag{ignore-checksums} --- Ignores errors verifying package @tech{checksums} (unsafe).}
 
- @item{@DFlag{no-setup} --- Does not run @exec{raco setup} after installation. This behavior is also the case if the
+  @item{@DFlag{no-setup} --- Does not run @exec{raco setup} after installation. This behavior is also the case if the
-       environment variable @envvar{PLT_PKG_NOSETUP} is set to any non-empty value.}
+        environment variable @envvar{PLT_PKG_NOSETUP} is set to any non-empty value.}
+
+  @item{@DFlag{skip-installed} --- Ignore a @nonterm{pkg-source} if a corresponding package is already installed.}
 
   @item{@DFlag{link} --- Implies @exec{--type dir} (and overrides any specified type),
         and links the existing directory as an installed package. The package is identified
@@ -327,6 +329,9 @@ sub-sub-commands:
  @item{@Flag{i} or @DFlag{installation} --- Shorthand for @exec{--scope installation}.}
  @item{@Flag{u} or @DFlag{user} --- Shorthand for @exec{--scope user}.}
  @item{@Flag{s} or @DFlag{shared} --- Shorthand for @exec{--scope shared}.}
+ 
+ @item{@DFlag{catalog} @nonterm{catalog} --- Use @nonterm{catalog} instead of of the currently configured 
+       @tech{package catalogs}.}
  ]
 }
 

pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl

@@ -918,6 +918,17 @@ v
   which means that this result is not sensitive to the value of the 
   @racket[use-user-specific-search-paths] parameter.}
 
+@defproc[(get-main-collects-search-dirs) (listof path?)]{
+  Returns a list of paths to installation @filepath{collects}
+  directories, including the result of @racket[find-collects-dir].
+  These directories are normally included in the result of
+  @racket[(current-library-collection-paths)], but a
+  @envvar{PLTCOLLECTS} setting or change to the parameter may cause
+  them to be omitted. Any other path in
+  @racket[(current-library-collection-paths)] is treated as
+  user-specific. The dierctories indicated by the returned paths may
+  or may not exist.}
+
 @defproc[(find-config-dir) path?]{
   Returns a path to the installation's @filepath{etc} directory, which
   contains configuration and package information---including
@@ -1098,43 +1109,48 @@ v
 
 @defproc[(find-relevant-directories
           (syms (listof symbol?))
-          (mode (or/c 'preferred 'all-available 'no-planet) 'preferred)) (listof path?)]{
+          (mode (or/c 'preferred 'all-available 'no-planet 'no-user) 'preferred)) 
+         (listof path?)]{
 
-   Returns a list of paths identifying installed directories (i.e.,
+   Returns a list of paths identifying
-   collections and installed @|PLaneT| packages) whose
+   collections and installed @|PLaneT| packages whose
    @filepath{info.rkt} file defines one or more of the given
    symbols. The result is based on a cache that is computed by
    @exec{raco setup}.
+
    Note that the cache may be out of date by the time you call
-   @racket[get-info/full], so do not assume that it won't return
+   @racket[get-info/full], so do not assume that every returned
-   @racket[#f].
+   directory's @filepath{info.rkt} file will supply one of the
+   requested sybols.
 
    The result is in a canonical order (sorted lexicographically by
    directory name), and the paths it returns are suitable for
    providing to @racket[get-info/full].
 
    If @racket[mode] is specified, it must be either
-   @racket['preferred] (the default), @racket['all-available], or @racket[no-planet]. If
+   @racket['preferred] (the default), @racket['all-available],
-   @racket[mode] is @racket['all-available], @racket[find-relevant-collections]
+   @racket['no-planet], or @racket['no-user]. If @racket[mode] is
-   returns all installed directories whose info files contain the
+   @racket['all-available], @racket[find-relevant-collections] returns
-   specified symbols---for instance, all installed PLaneT packages
+   all installed directories whose info files contain the specified
-   will be searched if @racket['all-available] is specified. If @racket[mode]
+   symbols---for instance, all versions of all installed PLaneT
-   is @racket['preferred], then only a subset of ``preferred''
+   packages will be searched if @racket['all-available] is
-   packages will be searched: only the directory
+   specified. If @racket[mode] is @racket['preferred], then only a
-   containing the most recent version of any PLaneT package will be
+   subset of ``preferred'' packages will be searched: only the
-   returned. If @racket[mode] is @racket['no-planet], then only  PLaneT
+   directory containing the most recent version of any PLaneT package
-   packages are not included in the search.
+   will be returned. If @racket[mode] is @racket['no-planet], then
+   PLaneT packages are not included in the search. If @racket[mode] is
+   @racket['no-user], then only installation-wide directories are
+   search, which means omitting @|PLaneT| package directories.
 
-   No matter what @racket[mode] is specified, if more than one
-   collection has the same name, @racket[find-relevant-directories]
-   will only search the one that occurs first in a search that through
-   the directories of @racket[current-library-collection-paths].
    Collection links from the installation-wide @tech[#:doc
-   reference-doc]{collection links file} are cached with the
+   reference-doc]{collection links file} or packages with installation
-   installation's main @filepath{collects} directory, and links from
+   scope are cached with the installation's main @filepath{lib}
-   the user-specific @tech[#:doc reference-doc]{collection links file}
+   directory, and links from the user-specific @tech[#:doc
-   are cached with the user-specific directory @racket[(build-path
+   reference-doc]{collection links file} and packages are cached with
-   (find-system-path 'addon-dir) (version) "collects")].}
+   the user-specific directory @racket[(build-path (find-system-path
+   'addon-dir) "collects")] for all-version cases, and in @racket[(build-path
+   (find-system-path 'addon-dir) (version) "collects")] for
+   version-specific cases.}
 
 @defproc[(find-relevant-directory-records
           [syms (listof symbol?)]

pkgs/racket-pkgs/racket-doc/scribblings/reference/filesystem.scrbl

@@ -86,8 +86,7 @@ by @racket[kind], which must be one of the following:
   ]}
 
  @item{@indexed-racket['config-dir] --- a directory for
- the installation's configuration, packages, and extensions.
+ the installation's configuration. This directory is specified by the
- This directory is specified by the
  @indexed-envvar{PLTCONFIGDIR} environment variable, and it can be
  overridden by the @DFlag{config} or @Flag{G} command-line flag.  If no
  environment variable or flag is specified, or if the value is not a
@@ -772,7 +771,8 @@ Displays each element of @racket[lst] to @racket[path], adding
 @racket[exists-flag] arguments are the same as for
 @racket[open-output-file].}
 
-@defproc[(copy-directory/files [src path-string?] [dest path-string?]) 
+@defproc[(copy-directory/files [src path-string?] [dest path-string?]
+                               [#:keep-modify-seconds? keep-modify-seconds? #f])
          void?]{
 
 Copies the file or directory @racket[src] to @racket[dest], raising
@@ -780,19 +780,35 @@ Copies the file or directory @racket[src] to @racket[dest], raising
 copied, possibly because @racket[dest] exists already. If @racket[src]
 is a directory, the copy applies recursively to the directory's
 content. If a source is a link, the target of the link is copied
-rather than the link itself.}
+rather than the link itself.
 
-@defproc[(delete-directory/files [path path-string?])
+If @racket[keep-modify-seconds?] is @racket[#f]false, then file copies
+keep only the properties kept by @racket[copy-file], If
+@racket[keep-modify-seconds?] is true, then each file copy also keeps
+the modification date of the original.}
+
+
+@defproc[(delete-directory/files [path path-string?]
+                                 [#:must-exist? must-exist? #t])
          void?]{
 
 Deletes the file or directory specified by @racket[path], raising
 @racket[exn:fail:filesystem] if the file or directory cannot be
 deleted. If @racket[path] is a directory, then
 @racket[delete-directory/files] is first applied to each file and
-directory in @racket[path] before the directory is deleted.}
+directory in @racket[path] before the directory is deleted.
+
+If @racket[must-exist?] is true, then @racket[exn:fail:filesystem] is
+raised if @racket[path] does not exist. If @racket[must-exist?] is
+false, then @racket[delete-directory/files] succeeds if @racket[path]
+does not exist (but a failure is possible if @racket[path] initially
+exists and is removed by another thread or process before 
+@racket[delete-directory/files] deletes it).}
+
 
 @defproc[(find-files [predicate (path? . -> . any/c)]
-                     [start-path (or/c path-string? #f) #f])
+                     [start-path (or/c path-string? #f) #f]
+                     [#:follow-links? follow-links? #f])
          (listof path?)]{
 
 Traverses the filesystem starting at @racket[start-path] and creates a
@@ -812,8 +828,10 @@ paths in the former case and relative paths in the latter.  Another
 difference is that @racket[predicate] is not called for the current
 directory when @racket[start-path] is @racket[#f].
 
-The @racket[find-files] traversal follows soft links. To avoid
+If @racket[follow-links?] is true, the @racket[find-files] traversal
-following links, use the more general @racket[fold-files] procedure.
+follows links, and links are not included in the result. If
+@racket[follow-links?] is @racket[#f], then links are not followed,
+and links are included in the result.
 
 If @racket[start-path] does not refer to an existing file or
 directory, then @racket[predicate] will be called exactly once with
@@ -822,7 +840,8 @@ directory, then @racket[predicate] will be called exactly once with
 The @racket[find-files] procedure raises and exception if it encounters 
 a directory for which @racket[directory-list] fails.}
 
-@defproc[(pathlist-closure [path-list (listof path-string?)])
+@defproc[(pathlist-closure [path-list (listof path-string?)]
+                           [#:follow-links? follow-links? #f])
          (listof path?)]{
 
 Given a list of paths, either absolute or relative to the current
@@ -840,7 +859,12 @@ directory, returns a list such that
  @item{ancestor directories appear before their descendants in the
        result list.}
 
-]}
+]
+
+If @racket[follow-links?] is true, then the traversal of directories
+and files follows links, and the link paths are not included in the
+result. If @racket[follow-links?] is @racket[#f], then he result list
+includes paths to link and the links are not followed.}
 
 
 @defproc[(fold-files [proc (or/c (path? (or/c 'file 'dir 'link) any/c 

pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/base.scrbl

@@ -522,10 +522,16 @@ with a word (e.g., ``section''), then the word is capitalized.}
                   [#:doc module-path (or/c module-path? #f) #f]
                   [#:tag-prefixes prefixes (or/c (listof string?) #f) #f]
                   [#:underline? underline? any/c #t]
+                  [#:indirect? indirect? any/c #f]
                   [pre-content pre-content?] ...) element?]{
 
 Like @racket[secref], but the link label is the @tech{decode}d
-@racket[pre-content] instead of the target section's name.}
+@racket[pre-content] instead of the target section's name.
+
+In addition to @racket[secref]'s arguments, @racket[seclink] supports
+a @racket[indirect?] argument. When @racket[indirect?] is true, then
+the section hyperlink's resolution in HTML is potentially delayed; see
+@racket['indirect-link] for @racket[link-element].}
 
 
 @defproc[(other-doc [module-path module-path?]

pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl

@@ -8,7 +8,8 @@
                      setup/main-collects
                      scriblib/render-cond
                      xml/xexpr
-                     net/url-structs))
+                     net/url-structs
+                     (only-in scribble/html-render render-mixin)))
 
 @title[#:tag "core"]{Structures And Processing}
 
@@ -907,7 +908,21 @@ When @racket[tag] is a part tag and the content of the element is
 @racket[null], then the hyperlink uses the target part's number and/or
 title as the content. In that case, if the section number is preceded
 by a word, the word starts in uppercase if the element's style includes a
-@racket['uppercase] property.}
+@racket['uppercase] property.
+
+The following symbol is recognized as a @tech{style property}:
+
+@itemize[
+
+ @item{@racket['indirect-link] --- For HTML output, treats the link as
+       ``external''. When rendering to HTML and the
+       @method[render-mixin set-external-tag-path] method is called to
+       provide an external-link URL, then the resolution of the
+       hyperlink can be deferred until the link is clicked (or, in
+       some cases, patched by JavaScript when the documentation is
+       viewed in a browser).}
+
+]}
 
 
 @defstruct[(index-element element) ([tag tag?]
@@ -1480,6 +1495,34 @@ Like @racket[latex-defaults], but use for the
 For a @racket[part] that corresponds to an HTML page, adds content to
 the @tt{<head>} tag.}
 
+
+@defstruct[part-link-redirect ([url url?])]{
+
+As a @tech{style property} on a @tech{part}, causes hyperiinks to the
+part to be redirected to @racket[url] instead of the rendered part.}
+
+@defstruct[link-resource ([path path-string?])]{
+
+As a @tech{style property} on an @racket[element], causes the elements
+to be rendered as a hyperlink to (a copy of) @racket[path].
+
+The file indicated by @racket[path] is referenced in place when
+@racket[render<%>] is instantiated with
+@racketidfont{refer-to-existing-files} as true. Otherwise, it is
+copied to the destination directory and potentially renamed to avoid
+conflicts.}
+
+
+@defstruct[install-resource ([path path-string?])]{
+
+Like @racket[link-resource], but makes @racket[path] accessible in the
+destination without rendering a hyperlink.
+
+This @tech{style property} is useful only when @racket[render<%>] is
+instantiated with @racketidfont{refer-to-existing-files} as
+@racket[#f], and only when @racket[path] does not match then name of
+any other file that is copied by the renderer to the destination.}
+
 @; ----------------------------------------
 
 @section{Latex Style Properties}

pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl

@@ -421,12 +421,20 @@ because the @"@"-reader would drop comments within the
 @; ------------------------------------------------------------------------
 @subsection{Code Fonts and Styles}
 
-@defform*[((racketmodname datum)
+@defform*[((racketmodname datum maybe-indirect)
-           (racketmodname ((unsyntax (racket unsyntax)) expr)))]{
+           (racketmodname ((unsyntax (racket unsyntax)) expr maybe-indirect)))
+          #:grammar ([maybe-indirect code:blank
+                                    #:indirect])]{
+
 Like @racket[racket], but typeset as a module path. If @racket[datum]
 is an identifier or @racket[expr] produces a symbol, then it is
 hyperlinked to the module path's definition as created by
-@racket[defmodule].}
+@racket[defmodule].
+
+If @racket[#:indirect] is specified, then the hyperlink is given the
+@racket['indirect-link] @tech{style property}, which makes the
+hyperlink's resolution in HTML potentially delayed; see
+@racket['indirect-link] for @racket[link-element].}
 
 @defform[(racketmodlink datum pre-content-expr ...)]{
 Like @racket[racketmod], but separating the module path to link

racket/lib/collects/setup/getinfo.rkt

@@ -206,7 +206,8 @@
              (cons (build-path coll "info-domain" "compiled" "cache.rktd")
                    coll))
            (if (eq? key 'no-user)
-               (list (find-collects-dir))
+               (remove* (get-main-collects-search-dirs)
+                        (current-library-collection-paths))
                (current-library-collection-paths)))
       (map (lambda (base)
              (cons (build-path base "info-cache.rktd")