From 4dc8050f757c529b30ee9960f9ec8c01c7f61ca5 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Wed, 26 Jun 2013 12:56:38 -0700 Subject: [PATCH] catch up on documentation for some library changes The library changes were made as part of the package reoganization. --- .../racket-doc/file/scribblings/tar.scrbl | 7 +- .../racket-doc/pkg/scribblings/lib.scrbl | 21 +++--- .../racket-doc/pkg/scribblings/pkg.scrbl | 9 ++- .../racket-doc/scribblings/raco/setup.scrbl | 64 ++++++++++++------- .../scribblings/reference/filesystem.scrbl | 46 +++++++++---- .../scribblings/scribble/base.scrbl | 8 ++- .../scribblings/scribble/core.scrbl | 47 +++++++++++++- .../scribblings/scribble/manual.scrbl | 14 +++- racket/lib/collects/setup/getinfo.rkt | 3 +- 9 files changed, 165 insertions(+), 54 deletions(-) diff --git a/pkgs/racket-pkgs/racket-doc/file/scribblings/tar.scrbl b/pkgs/racket-pkgs/racket-doc/file/scribblings/tar.scrbl index 6b6d1c60b2..03396eb055 100644 --- a/pkgs/racket-pkgs/racket-doc/file/scribblings/tar.scrbl +++ b/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?]{ diff --git a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/lib.scrbl b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/lib.scrbl index 70f2ed8875..e0410f9d20 100644 --- a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/lib.scrbl +++ b/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}, -and returns a string for the collection contained by the package if @racket[dir] -represents a @tech{single-collection package}. +Returns a string for a collection name if @racket[dir] represents a +@tech{single-collection package}, or returns @racket[#f] if @racket[dir] +represents a @tech{multi-collection package}. -Detecting a @tech{single-collection package} may involve loading an -@filepath{info.rkt} file via @racket[getinfo/full], in which case -@racket[namespace] is used.} +For some single-collection packages, the package's single collection +is the package name; if the package name is different from the +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?] diff --git a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/pkg.scrbl b/pkgs/racket-pkgs/racket-doc/pkg/scribblings/pkg.scrbl index 965bee66b2..3320d218bb 100644 --- a/pkgs/racket-pkgs/racket-doc/pkg/scribblings/pkg.scrbl +++ b/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 - environment variable @envvar{PLT_PKG_NOSETUP} is set to any non-empty value.} + @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.} + + @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}.} ] } diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl index fc07b4430c..36c1e33bb8 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl +++ b/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., - collections and installed @|PLaneT| packages) whose + Returns a list of paths identifying + 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[#f]. + @racket[get-info/full], so do not assume that every returned + 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[mode] is @racket['all-available], @racket[find-relevant-collections] - returns all installed directories whose info files contain the - specified symbols---for instance, all installed PLaneT packages - will be searched if @racket['all-available] is specified. If @racket[mode] - is @racket['preferred], then only a subset of ``preferred'' - packages will be searched: only the directory - containing the most recent version of any PLaneT package will be - returned. If @racket[mode] is @racket['no-planet], then only PLaneT - packages are not included in the search. + @racket['preferred] (the default), @racket['all-available], + @racket['no-planet], or @racket['no-user]. If @racket[mode] is + @racket['all-available], @racket[find-relevant-collections] returns + all installed directories whose info files contain the specified + symbols---for instance, all versions of all installed PLaneT + packages will be searched if @racket['all-available] is + specified. If @racket[mode] is @racket['preferred], then only a + subset of ``preferred'' packages will be searched: only the + directory containing the most recent version of any PLaneT package + 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 - installation's main @filepath{collects} directory, and links from - the user-specific @tech[#:doc reference-doc]{collection links file} - are cached with the user-specific directory @racket[(build-path - (find-system-path 'addon-dir) (version) "collects")].} + reference-doc]{collection links file} or packages with installation + scope are cached with the installation's main @filepath{lib} + directory, and links from the user-specific @tech[#:doc + reference-doc]{collection links file} and packages are cached with + 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?)] diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/reference/filesystem.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/reference/filesystem.scrbl index 37da3b4ef2..5a3b567548 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/reference/filesystem.scrbl +++ b/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. - This directory is specified by the + the installation's configuration. 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 -following links, use the more general @racket[fold-files] procedure. +If @racket[follow-links?] is true, the @racket[find-files] traversal +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 diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/base.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/base.scrbl index fa60aea7ab..43b7c1f0d4 100644 --- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/base.scrbl +++ b/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?] diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl index c33b4a897f..2b6cecc90e 100644 --- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl +++ b/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{} 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} diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl index 652eaca913..2769556593 100644 --- a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl +++ b/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) - (racketmodname ((unsyntax (racket unsyntax)) expr)))]{ +@defform*[((racketmodname datum maybe-indirect) + (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 diff --git a/racket/lib/collects/setup/getinfo.rkt b/racket/lib/collects/setup/getinfo.rkt index 1d19dd7b0f..7982349272 100644 --- a/racket/lib/collects/setup/getinfo.rkt +++ b/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")