From a6e135c75c168d8a51545ff4a44c94b1c3db1db8 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. original commit: 4dc8050f757c529b30ee9960f9ec8c01c7f61ca5 --- .../scribblings/scribble/base.scrbl | 8 +++- .../scribblings/scribble/core.scrbl | 47 ++++++++++++++++++- .../scribblings/scribble/manual.scrbl | 14 ++++-- 3 files changed, 63 insertions(+), 6 deletions(-) diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/base.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/base.scrbl index fa60aea7..43b7c1f0 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 c33b4a89..2b6cecc9 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 652eaca9..27695565 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