On this page:
setup
current-cover-dc
finish-cover
2.1 Spine width calculators
createspace-spine
using-ppi
2.2 Drawing functions
cover-draw
frontcover-draw
backcover-draw
spine-draw
outline-spine!
outline-bleed!
2.3 Measurement functions
bleed
pageheight
coverheight
pagewidth
spinewidth
coverwidth
spineleftedge
spinerightedge
centering-offset
2.4 Testing
dummy-pdf
check-cover
2.5 Unit conversion functions
inches->pts
cm->pts
pts->inches-string
pts->cm-string
7.2

2 Module Reference

 (require bookcover/draw) package: bookcover

This module is automatically provided by #lang bookcover. The only difference between the require form and #lang bookcover is that with the former, finish-cover is not automatically called at the end of your program. You might prefer to use the require form when doing something fancier than creating just a single static cover; for example, when defining your own functions that create multiple book covers of the same style for different titles.

procedure

(setup #:interior-pdf interior-pdf    
  #:cover-pdf cover-pdf-filename    
  [#:bleed-pts bleed-pts    
  #:spine-calculator spinewidth-calc])  void?
  interior-pdf : path-string?
  cover-pdf-filename : path-string?
  bleed-pts : real? = (* 0.125 72)
  spinewidth-calc : (exact-positive-integer? . -> . real?)
   = (createspace-spine 'white-bw)
Calculate the size of the book cover that would properly fit an existing PDF file interior-pdf; set the return values for all the Measurement functions; and create a pdf-dc% object for drawing on the book cover, which will be saved as cover-pdf-filename.

The cover dimensions are calculated as follows:

  1. The width and height of the first page in interior-pdf are used as the size of the front and back covers.

  2. The page count of interior-pdf is passed to spinewidth-calc to determine the width of the spine. (See spine width calculators.)

  3. A width equal to bleed-pts is added to all four edges of the cover.

Examples:

; The minimum viable setup call
(setup #:interior-pdf "my-book-contents.pdf"
       #:cover-pdf "cover.pdf")
 
; Using more options:
(setup #:interior-pdf "my-book-contents.pdf"
       #:cover-pdf "cover.pdf"
       #:spinewidth-calc (using-ppi 339) ; Calculate spine width using 339 PPI
       #:bleed-pts (inches->pts 0.25))   ; Use 1/4" bleed

procedure

(current-cover-dc)  (or/c null? (is-a?/c pdf-dc%))

Returns the pdf-dc% object for the currently active book cover, in case you want to draw on it directly with functions in racket/draw.

If setup has not yet been called since the start of the program, or if it hasn’t been called since the last time finish-cover was called, then there is no active cover, and current-cover-dc will return null.

procedure

(finish-cover)  void?

Properly closes the pdf-dc% for the current book cover, sets current-cover-dc to null, and zeroes out the return values of all the Measurement functions.

If current-cover-dc is already null, calling this function has no effect.

This function is automatically called at the very end of your program when using #lang bookcover.

It is also called automatically on successive calls to setup whenever current-cover-dc is not equal to null.

2.1 Spine width calculators

In order to properly calculate the overall width of the book cover, the module needs (among other things) a way to calculate the thickness of your book’s spine.

This spine width calculator is any function that takes a page count (a positive integer) and returns a value in points.

You may pass any such function to the #:spine-calculator argument of setup; if you choose not to, setup will default to the function returned by (createspace-spine 'white-bw) that is, it will assume you are having your book printed by Createspace, on their white paper, in black and white.

Different printers specify different ways of calculating the spine width of your book. As a convenience, this module provides some functions which return ready-made spine width calculators that cover the most common cases, but you can also supply your own.

procedure

(createspace-spine paper-type)

  (exact-positive-integer? . -> . real?)
  paper-type : (or/c 'white-bw 'cream-bw 'color)
Returns a spine width calculator function that uses the constants provided by Createspace for their different paper types: 0.002252 for black-and-white printing on white paper, 0.0025 for black-and-white printing on cream paper, and 0.002347 for color printing.

Examples:
> (define spine-func (createspace-spine 'cream-bw))
> (spine-func 330)

59.400000000000006

procedure

(using-ppi pages-per-inch)

  (exact-positive-integer? . -> . real?)
  pages-per-inch : real?
Returns a spine width calculator function that multiplies its page-count argument by (/ 1 pages-per-inch 72.0) to get a width in points.

Use this if your printing service instructs you to calculate spine width using a PPI value for a particular paper type.

Examples:
> (define ppi-spine (using-ppi 442))
> (ppi-spine 78)

12.705882352941178

2.2 Drawing functions

procedure

(cover-draw pic x y)  void?

  pic : pict-convertible?
  x : real?
  y : real?
Draw pic on the current cover, with its top left corner at x, y. The 0 coordinates for x and y start on the very outside edge of the bleed.

procedure

(frontcover-draw pic    
  [#:top top    
  #:left left    
  #:horiz-center? hcenter    
  #:vert-center? vcenter])  void?
  pic : pict-convertible?
  top : real? = 0
  left : real? = 0
  hcenter : any/c = #f
  vcenter : any/c = #f

procedure

(backcover-draw pic    
  [#:top top    
  #:left left    
  #:horiz-center? hcenter    
  #:vert-center? vcenter])  void?
  pic : pict-convertible?
  top : real? = 0
  left : real? = 0
  hcenter : any/c = #f
  vcenter : any/c = #f
Draw pic on the “front” or “back” regions cover, using coordinates and centering relative to the respective region.

; These two lines do exactly the same thing:
(cover-draw pic 0 0)
(backcover-draw pic)
 
; These two lines also do exactly the same thing:
(cover-draw pic (spinerightedge) 0)
(frontcover-draw pic)

The 0 coordinates for either function’s #:top argument (as well as the #:left argument of backcover) start at the very outside edge of the bleed.

When hcenter is #t, left is ignored; likewise when vcenter is #t, top is ignored.

procedure

(spine-draw pic [top-offset])  void?

  pic : pict-convertible?
  top-offset : real? = 0
Draw pic horizontally centered on the spine, optionally offset from the top of the spine by top-offset.

By design, this function does not check or care if pic will fit inside spinewidth.

; Draw some text on the spine
(define spine-title
  (text "My Book Title" "Helvetica" 10 (degrees->radians 270)))
 
(spine-draw spine-title (centering-offset spine-title page-height pict-height))
 
; Draw a blue rectangle that wraps around the spine equally on front and back
(define spine-rectangle
  (filled-rectangle (* (spinewidth) 4)
                    (pageheight)
                    #:color "lightblue"
                    #:draw-border #f))
 
(spine-draw spine-rectangle)

procedure

(outline-spine! [#:color color])  void?

  color : (or/c string? (is-a?/c color%) (list/c byte? byte? byte?))
   = "black"

procedure

(outline-bleed! [#:color color])  void?

  color : (or/c string? (is-a?/c color%) (list/c byte? byte? byte?))
   = "black"
Draw an outline of the spine or bleed areas, respectively, on the cover, using a dashed line colored with color. Useful for verifying placement, but you will want to omit these outlines from your finished cover.

2.3 Measurement functions

When setting up your cover, everything is specified in points. But when you ask Racket for the dimensions of the PDF object you’ve just created, you’ll get a different value than the point value you specified. This is because PDF objects in Racket also have a scaling factor (0.8 by default) that is applied to each dimension when the object is created. So if you specify that your cover should have a bleed of 9 points (1/8 inch), the “actual” width — the one returned by the bleed function — will be generally be 11.25. These scaled values are the ones you must use when drawing on the cover.

procedure

(bleed)  real?

procedure

(pageheight)  real?

procedure

(coverheight)  real?

procedure

(pagewidth)  real?

procedure

(spinewidth)  real?

procedure

(coverwidth)  real?

Return the actual measurement of the element on the current-cover-dc, already divided by the scaling factor. The coverheight function is identical to pageheight.

The pagewidth, pageheight and coverwidth functions each include the width of the bleed on all applicable sides:

procedure

(spineleftedge)  real?

procedure

(spinerightedge)  real?

Returns the x-coordinate of the spine’s left or right edge on the current-cover-dc, already divided by the scaling factor.

procedure

(centering-offset pic context-dim [dim-func])  real?

  pic : pict-convertible?
  context-dim : real?
  dim-func : (pict? . -> . real?) = pict-width
Returns an offset that, when used as an x- or y-offset for pic, would exactly center it within context-dim.

If centering vertically, use pict-height as the last argument.

Examples:
> (define blue-rectangle (filled-rectangle 20 60 #:color "blue"))
> (centering-offset blue-rectangle 100)

40

> (centering-offset blue-rectangle 250 pict-height)

95

2.4 Testing

procedure

(dummy-pdf output-pdf    
  width-pts    
  height-pts    
  [#:pages page-count])  void?
  output-pdf : path-string?
  width-pts : real?
  height-pts : real?
  page-count : exact-positive-integer? = 1
Creates a PDF with page-count pages using the given dimensions and saves it to output-pdf. The width and height are given in points. If output-pdf exists, it will be silently overwritten.

This PDF can be useful for mocking up a cover if you don’t yet have a PDF of your book’s interior to pass to the setup function, or for rapidly experimenting with different paper sizes. See the documentation for check-cover for an example.

procedure

(check-cover [#:unit-display unit-func])  void?

  unit-func : (real? . -> . string?) = pts->inches-string
Prints out a bunch of information about the current bleed, interior PDF page size, spine width calculation and cover size. Dimensions are formatted using unit-func.

Examples:
> (dummy-pdf "my-book.pdf" (inches->pts 4) (inches->pts 6) #:pages 100)
> (setup #:interior-pdf "my-book.pdf"
         #:cover-pdf "my-cover.pdf")
> (check-cover)

pdf-dc% get-size:     763.75 ⨉ 562.5

Cover size (w/bleed): 8.475″ ⨉ 6.25″ (610.2144pts ⨉ 450.0pts, w/scaling 762.768 ⨉ 562.5)

Scaling factor:       0.8

Bleed:                0.125″ (11.25)

Interior PDF size:    4.0″ ⨉ 6.0″

Interior pagecount:   100 pages

Spine multiplier:     0.162144

Spine width:          0.225″ (100 pages ⨉ 0.162144 = 16.2144 pts)

CreateSpace would not allow text on spine (pages < 101)

2.5 Unit conversion functions

procedure

(inches->pts inches)  real?

  inches : real?

procedure

(cm->pts cm)  real?

  cm : real?
Convert inches and cm to points, respectively. Created mainly for convenience with setup and dummy-pdf.

Examples:
> (inches->pts 1)

72.0

> (cm->pts 1)

28.346456692913385

procedure

(pts->inches-string points)  string?

  points : real?

procedure

(pts->cm-string points)  string?

  points : real?
Convert points to inches or centimeters, respectively, in string form with the unit appended. Included for use with check-cover, though perhaps you will find other uses for them.

Examples:
> (pts->inches-string 72)

"1.0″"

> (pts->cm-string 72)

"2.54cm"