From 2b27ed487215867bc1aa371a27ecb53ccbc336b2 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Fri, 11 Apr 2008 02:07:15 +0000
Subject: [PATCH] doc updates

svn: r9250
---
 collects/games/cards/cards.scrbl           |  2 +-
 collects/games/scribblings/games.scrbl     | 24 ++++++++++++++++++----
 collects/scribblings/scribble/basic.scrbl  | 18 +++++++++++++++-
 collects/scribblings/scribble/struct.scrbl | 10 ++++++---
 4 files changed, 45 insertions(+), 9 deletions(-)

diff --git a/collects/games/cards/cards.scrbl b/collects/games/cards/cards.scrbl
index 81ac143173..c76f7fda56 100644
--- a/collects/games/cards/cards.scrbl
+++ b/collects/games/cards/cards.scrbl
@@ -1,6 +1,6 @@
 #lang scribble/doc
 @(require scribble/manual
-          (for-label "main.ss"
+          (for-label games/cards
                      scheme/gui/base))
 
 @title{@bold{Cards}: Virtual Playing Cards Library}
diff --git a/collects/games/scribblings/games.scrbl b/collects/games/scribblings/games.scrbl
index 98422c9c33..283683b884 100644
--- a/collects/games/scribblings/games.scrbl
+++ b/collects/games/scribblings/games.scrbl
@@ -1,5 +1,9 @@
 #lang scribble/doc
-@(require "common.ss")
+@(require "common.ss"
+          (for-label scheme/base
+                     scheme/contract
+                     games/show-help
+                     games/show-scribbling))
 
 @title{@bold{Games}}
 
@@ -51,7 +55,21 @@ typically belong in the @scheme["Cards"] game set.
 
 @; ----------------------------------------------------------------------
 
-@section{Showing Help}
+@section{Showing Scribbled Help}
+
+@defmodule[games/show-scribbling]
+
+@defproc[(show-scribbling [mod-path module-path?]
+                          [section-tag string?])
+         (-> void?)]{
+
+Returns a thunk for opening a Scribbled section in the user's HTML
+browser. The @scheme[mod-path] is the document's main source module,
+and @scheme[section-tag] specifies the section in the document.}
+
+@; ----------------------------------------------------------------------
+
+@section{Showing Text Help}
 
 @defmodule[games/show-help]
 
@@ -85,5 +103,3 @@ verbatim, otherwise it is formatted as follows:
  @item{Other lines are paragraph-flowed to fit the window.}
 
 ]}
-
-
diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl
index fffdda27ed..c2bff39a89 100644
--- a/collects/scribblings/scribble/basic.scrbl
+++ b/collects/scribblings/scribble/basic.scrbl
@@ -1,12 +1,15 @@
 #lang scribble/doc
 @(require scribble/manual
           "utils.ss"
-          (for-syntax scheme/base))
+          (for-syntax scheme/base)
+          (for-label setup/main-collects))
 
 @(define-syntax def-section-like
    (syntax-rules ()
      [(_ id result/c x ...)
       (defproc (id [#:tag tag (or/c false/c string?) #f]
+                   [#:tag-prefix tag-prefix (or/c false/c string? module-path?) #f]
+                   [#:style style any/c #f]
                    [pre-content any/c] (... ...+))
         result/c
         x ...)]))
@@ -51,6 +54,7 @@ have @schememodname[scribble/manual]).
 @section{Document Structure}
 
 @defproc[(title [#:tag tag (or/c false/c string?) #f]
+                [#:tag-prefix tag-prefix (or/c false/c string? module-path?) #f]
                 [#:style style any/c #f]
                 [#:version vers (or/c string? false/c) #f]
                 [pre-content any/c] ...+)
@@ -68,6 +72,11 @@ separate pages in multi-page HTML output. A style of @scheme['index]
 indicates an index section whose body is rendered in two columns for
 Latex output.
 
+The @scheme[tag-prefix] argument is propagated to the generated
+structure (see @secref["tags"]). If @scheme[tag-prefix] is a module
+path, it is converted to a string using
+@scheme[module-path-prefix->string].
+
 The @scheme[vers] argument is propagated to the @scheme[title-decl]
 structure.
 
@@ -117,6 +126,13 @@ Returns @scheme[#t] if @scheme[v] is an item produced by
  visible to the enclosing context). Since this form expands to
  @scheme[require], it must be used in a module or top-level context.}
 
+@defproc[(module-path-prefix->string [mod-path module-path?])
+         string?]{
+
+Converts a module path to a string by resolving it to a path, and
+using @scheme[path->main-collects-relative].}
+
+
 @; ------------------------------------------------------------------------
 
 @section{Text Styles}
diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl
index 1863257613..1626cdad00 100644
--- a/collects/scribblings/scribble/struct.scrbl
+++ b/collects/scribblings/scribble/struct.scrbl
@@ -1,7 +1,8 @@
 #lang scribble/doc
 @(require scribble/manual
           "utils.ss"
-          (for-label scribble/manual-struct))
+          (for-label scribble/manual-struct
+                     setup/main-collects))
 
 @title[#:tag "struct"]{Structures And Processing}
 
@@ -512,10 +513,13 @@ Used as a style for an @scheme[element]. The @scheme[style] at this
 layer is a style for the hyperlink.}
 
 
-@defstruct[image-file ([path path-string?]
+@defstruct[image-file ([path (or/c path-string?
+                                   (cons/c 'collects (listof bytes?)))]
                        [scale real?])]{
 
-Used as a style for an @scheme[element].}
+Used as a style for an @scheme[element] to inline an image. The
+@scheme[path] field can be a result of
+@scheme[path->main-collects-relative].}
 
 
 @defproc[(block? [v any/c]) boolean?]{