suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

catch up on documentation for some library changes

Browse Source 
The library changes were made as part of the package reoganization.
This commit is contained in:
Matthew Flatt 2013-06-26 12:56:38 -07:00
parent dc11090f6b
commit 4dc8050f75
9 changed files with 165 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
pkgs/racket-pkgs/racket-doc/file/scribblings/tar.scrbl
View File

@ -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?]{

21
pkgs/racket-pkgs/racket-doc/pkg/scribblings/lib.scrbl
View File

@ -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?]

9
pkgs/racket-pkgs/racket-doc/pkg/scribblings/pkg.scrbl
View File

@ -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}.}
]
}

64
pkgs/racket-pkgs/racket-doc/scribblings/raco/setup.scrbl
View File

@ -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?)]

46
pkgs/racket-pkgs/racket-doc/scribblings/reference/filesystem.scrbl
View File

@ -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

8
pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/base.scrbl
View File

@ -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?]

47
pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/core.scrbl
View File

@ -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}

14
pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl
View File

@ -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

3
racket/lib/collects/setup/getinfo.rkt
View File

@ -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")