[racket] help with scribble/manual

From: Danny Heap (heap at cs.toronto.edu)
Date: Mon May 21 15:36:41 EDT 2012

I am trying to include a small manual page with my (also small)
PLaneT module.  Scribble doesn't see the bindings for the functions
introduced in my module, judging by the warnings generated by 'raco
setup...' --- errors which are also generated when the module is
required from the PLanet repository.  I was also unable to use
@examples[], presumably for the same reason.

I suppose I could work around the alarming error messages by omitting
the documentation, but that seems counter-productive.  Any
suggestions?

I attach my info.rkt, main.rkt, manual.scrbl files, and the errors
generated when the module is required.  I made a development link to
the directory containing those files, ran 'raco setup', created a
repository with 'racket planet create...', and then uploaded the
repository.

-- 
Danny Heap
BA4270			416-978-5899
heap at cs.utoronto.ca	http://www.cs.utoronto.ca/~heap

#lang setup/infotab

(define name "Color Utilities")
(define blurb
  '("Tools to make 2htdp/image manipulation of colors more convenient"))
(define release-notes
  '((ul
     (li "Attempt to fix non-fatal documentation errors."))))
(define primary-file "main.rkt")
(define repositories '("4.x"))
(define categories '(media))
(define scribblings '(("manual.scrbl" ())))

#lang racket

(require test-engine/racket-tests)
(require 2htdp/image)

(provide +color 
         green+color
         blue+color
         red+color
         alpha+color 
         <-component
         for/image)

; exact-round : Number -> Number
; Produce exact, rounded x.
(define (exact-round x) (inexact->exact (round x)))
;
(check-expect (exact-round 1.6) 2)

; +color : symbol color value -> color
; Add component intensity val to col
(define (+color component val col)
  (color
   (if (eq? component 'red) (exact-round val) (color-red col))
   (if (eq? component 'green) (exact-round val) (color-green col))
   (if (eq? component 'blue) (exact-round val) (color-blue col))
   (if (eq? component 'alpha) (exact-round val) (color-alpha col))))
;
(check-expect (+color 'green 5 (color 1 2 3)) (color 1 5 3))

; <-component : symbol color -> color
; Produce component band of old
(define (<-component band old)
  ((cond
     [(equal? band 'red) color-red]
     [(equal? band 'green) color-green]
     [(equal? band 'blue) color-blue]
     [(equal? band 'alpha) color-alpha])
   old))
;
(check-expect (<-component 'blue (color 1 2 3 4)) 3)

; green+color : color value -> color
; Add green intensity val to col.
(define (green+color val col) (+color 'green val col))
;
(check-expect (green+color 10 (color 1 2 3 4)) (color 1 10 3 4))

; red+color : color value -> color
; Add red intensity val to col.
(define (red+color val col) (+color 'red val col))
;
(check-expect (red+color 10 (color 1 2 3 4)) (color 10 2 3 4))

; blue+color : color value -> color
; Add blue intensity val to col.
(define (blue+color val col) (+color 'blue val col))
;
(check-expect (blue+color 10 (color 1 2 3 4)) (color 1 2 10 4))

; alpha+color : color value -> color
; Add alpha intensity val to col.
(define (alpha+color val col) (+color 'alpha val col))
;
(check-expect (alpha+color 10 (color 1 2 3 4)) (color 1 2 3 10))

; for/image : ((id Image) ...+) expr -> Image
; Apply expr to bindings of ids to Image colors
; to produce a new image.
(define-syntax-rule
  (for/image ((id0 expr0) (id expr) ...)
             color-expr0 color-expr ...)
  (color-list->bitmap
   (for/list ([id0 (image->color-list expr0)]
              [id (image->color-list expr)] ...)
     color-expr0 color-expr ...)
   (image-width expr0)
   (image-height expr0)))

#;
(test)

#lang scribble/manual

@(require planet/scribble
          racket
          2htdp/image
          (this-package-in main))

@(require (for-label racket
                     (this-package-in main)
                     2htdp/image))

@(defmodule/this-package main)
@title{Color Utilities}

These are some convenience tools to transform images
in the 2htdp/image library.  The convenience consists of producing new colors by
changing a single intensity by name, and a for-like comprehension for images.

@defproc[(<-component [band symbol?] [old color?])
         (color)]{Produces @racket[band] portion @racket[old]'s @racket[color].}         
                 
@defproc[(+color [component symbol?] [val number?] [col color?])
         (color)]{Produces @racket[color] based on @racket[old], but
                 using intensity @racket[val] in band corresponding
                 to @racket[component].}
                 
@defproc[(green+color [val number?] [col color?])
         (color)]{Produces @racket[color] based on @racket[col], but
                  with the green intensity to @racket[val].  @racket[red+color],
                  @racket[blue+color], @racket[alpha+color] are analogous.}

@defform[(for/image ([id image-expr] ...)
           body ...+)]{Produce new @racket[image] by binding @racket[id]
                       to each element of @racket[image-expr]'s @racket[color-list]
                       in turn.}

Welcome to DrRacket, version 5.2.1 [3m].
Language: racket; memory limit: 512 MB.
make-script: unexpected value rendered: '((font ((class "badlink")) (span ((class "indexlink")) (span ((class "RktPn")) "(") (span ((class "RktSym")) (span ((class "RktStxLink")) "planet")) (span ((class "stt")) " ") (span ((class "RktSym")) "dsheap/color-utils:1:=0") (span ((class "Rkt...
raco setup: error: during Building docs for /usr/local/racket/collects/scribblings/main/user/search.scrbl
raco setup:   make-script: unexpected value rendered: '((font ((class "badlink")) (span ((class "indexlink")) (span ((class "RktPn")) "(") (span ((class "RktSym")) (span ((class "RktStxLink")) "planet")) (span ((class "stt")) " ") (span ((class "RktSym")) "dsheap/color-utils:1:=0") (span ((class "Rkt...
> 


----- End forwarded message -----

-- 
Danny Heap
BA4270			416-978-5899
heap at cs.utoronto.ca	http://www.cs.utoronto.ca/~heap

Posted on the users mailing list.