commit 0e5dd24c61217735ae1c308a826dd921973b4dd4
parent 0170b0a672c533afb5d4c0b9bcc5856a4e6c88d7
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Mon, 22 Jul 2013 18:13:46 -0600
show package for each module in documentation
The package is normally determined automatcially, but
the `defmodule' form also supports a `#:packages' option.
original commit: 5457f72391d83615e21924537e3a60749232d1f6
Diffstat:
4 files changed, 105 insertions(+), 28 deletions(-)
diff --git a/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl b/pkgs/scribble-pkgs/scribble-doc/scribblings/scribble/manual.scrbl
@@ -538,7 +538,8 @@ corresponding @racketidfont{racket...} binding.}
(code:line #:use-sources (src-module-path ...))
(code:line #:link-target? link-target?-expr)
#:lang
- #:reader])]{
+ #:reader
+ (code:line #:packages (pkg-expr ...))])]{
Produces a sequence of flow elements (in a @racket[splice])
to start the documentation for a module---or for multiple modules, if
@@ -590,6 +591,13 @@ If @racket[#:reader] is provided, then the module name is shown after
@racketmetafont{#reader} to indicate that the module path is intended
for use as a reader module.
+By default, the package (if any) that supplies the documented module
+is determined automatically, but a set of providing packages can be
+specified explicitly with @racket[#:packages]. Each @racket[pkg-expr]
+result is passed on to a function like @racket[tt] for
+typesetting. Provide an empty sequence after @racket[#:packages] to
+suppress any package name in the output.
+
Each @racket[option] form can appear at most once, and @racket[#:lang]
and @racket[#:reader] are mutually exclusive.
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-mod.rkt b/pkgs/scribble-pkgs/scribble-lib/scribble/private/manual-mod.rkt
@@ -3,9 +3,14 @@
"../struct.rkt"
"../basic.rkt"
"../manual-struct.rkt"
+ (only-in "../core.rkt" table-columns)
"manual-ex.rkt"
"manual-style.rkt"
"manual-scheme.rkt"
+ "manual-utils.rkt"
+ setup/main-collects
+ pkg/path
+ racket/list
(for-syntax scheme/base
syntax/parse)
(for-label scheme/base))
@@ -38,8 +43,6 @@
(make-element (make-style #f (list (make-background-color-property "yellow"))) content))
;; ---------------------------------------------------------------------------------------------------
-(define spacer (hspace 1))
-
(begin-for-syntax
(define-splicing-syntax-class link-target?-kw
#:description "#:link-target? keyword"
@@ -57,6 +60,7 @@
#:defaults ([link-target-expr #'#t]))
(~optional (~seq #:use-sources (pname ...)))
(~optional (~seq #:module-paths (modpath ...)))
+ (~optional (~seq #:packages (pkg ...)))
(~optional (~and #:no-declare no-declare))
(~optional (~or (~and #:lang language)
(~and #:reader readr))))
@@ -81,6 +85,15 @@
[modpaths (if (attribute modpath)
#'(list (racketmodname modpath) ...)
#'#f)]
+ [packages (if (attribute pkg)
+ #'(list pkg ...)
+ #'#f)]
+ [module-path (let ([l (syntax->list
+ (if (attribute modpath)
+ #'(modpath ...)
+ #'(name2 ...)))])
+ (and (pair? l)
+ (car l)))]
[req (if (attribute req)
#'req
#'(racket require))]
@@ -92,6 +105,8 @@
decl-exp ...
(*defmodule (list show-name ...)
modpaths
+ 'module-path
+ packages
link-target-expr
kind
(list . content)
@@ -167,35 +182,83 @@
;; ----------------------------------------
-(define (*defmodule names modpaths link-target? lang content req)
+(define (*defmodule names modpaths module-path packages link-target? lang content req)
(let ([modpaths (or modpaths names)])
+ (define pkg-spec
+ (let ([pkgs
+ (or packages
+ (let* ([path (with-handlers ([exn:missing-module? (lambda (exn) #f)])
+ (and module-path
+ (resolved-module-path-name
+ (module-path-index-resolve (module-path-index-join module-path #f)))))]
+ [pkg (and path
+ (or (path->pkg path)
+ (let ([c (path->main-collects-relative path)])
+ (and c
+ "base"))))])
+ (if pkg
+ (list pkg)
+ null)))])
+ (and pkgs
+ (pair? pkgs)
+ (make-flow
+ (list
+ (make-omitable-paragraph
+ (list (elem #:style "RpackageSpec"
+ (list* (smaller (format "package~a:"
+ (if (null? (cdr pkgs))
+ ""
+ "s")))
+ " "
+ (add-between (map tt pkgs) ", "))))))))))
+ (define (flow-width f) (apply max (map block-width f)))
+ (define libs-specs
+ (map
+ (lambda (name modpath)
+ (define modname (if link-target?
+ (make-defracketmodname name modpath)
+ name))
+ (list
+ (make-flow
+ (list
+ (make-omitable-paragraph
+ (cons
+ spacer
+ (case lang
+ [(#f)
+ (list (racket (#,req #,modname)))]
+ [(#t)
+ (list (hash-lang) spacer modname)]
+ [(reader)
+ (list (racketmetafont "#reader") spacer modname)]
+ [(just-lang)
+ (list (hash-lang) spacer modname)]
+ [else (error 'defmodule "unknown mode: ~e" lang)])))))
+ 'cont))
+ names
+ modpaths))
+
(make-splice
(cons
(make-table
- "defmodule"
- (map
- (lambda (name modpath)
- (define modname (if link-target?
- (make-defracketmodname name modpath)
- name))
- (list
- (make-flow
- (list
- (make-omitable-paragraph
- (cons
- spacer
- (case lang
- [(#f)
- (list (racket (#,req #,modname)))]
- [(#t)
- (list (hash-lang) spacer modname)]
- [(reader)
- (list (racketmetafont "#reader") spacer modname)]
- [(just-lang)
- (list (hash-lang) spacer modname)]
- [else (error 'defmodule "unknown mode: ~e" lang)])))))))
- names
- modpaths))
+ (make-style "defmodule"
+ (list (table-columns (list
+ (make-style #f '(left))
+ (make-style #f '(right))))))
+ (if pkg-spec
+ (if ((+ (flow-width (caar libs-specs))
+ (flow-width pkg-spec)
+ 8)
+ . < . (current-display-width))
+ (cons
+ (cons (car (car libs-specs))
+ (list pkg-spec))
+ (cdr libs-specs))
+ (append
+ libs-specs
+ (list (list (make-flow (list (make-omitable-paragraph (list 'nbsp))))
+ pkg-spec))))
+ libs-specs))
(append (if link-target?
(map (lambda (modpath)
(make-part-tag-decl
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/racket.css b/pkgs/scribble-pkgs/scribble-lib/scribble/racket.css
@@ -206,6 +206,10 @@
margin: 0em 0em 0em 0em;
}
+.RpackageSpec {
+ padding-right: 0.5em;
+}
+
/* ---------------------------------------- */
/* For background labels */
diff --git a/pkgs/scribble-pkgs/scribble-lib/scribble/racket.tex b/pkgs/scribble-pkgs/scribble-lib/scribble/racket.tex
@@ -67,3 +67,5 @@
\newcommand{\RBackgroundLabel}[1]{}
\newenvironment{RBackgroundLabelInner}{}{}
+
+\newcommand{\RpackageSpec}[1]{\hspace{5ex} #1}
