racket / racket/scribble

`margin-note` exceeds page limit in PDF e.g. Racket guide

Open
#470 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Racket
Stars
250
Forks
102
Avg merge
11d 11h
Merged PRs (30d)
1

Description

What version of Racket are you using?
8.15

What program did you run?
scribble/manual render to pdf

example showing continuation-mark-set->context running beyond edge of page in pdf viewer
Image

page 226
https://download.racket-lang.org/releases/8.15/pdf-doc/guide.pdf

What should have happened?

I'd expect scribble to wrap keep margin notes within gutter by wrapping @racket[continuation-mark-set->context] on hyphens like exn-message in @interaction block on the same page.(see full page capture below).

Not a big issue as manual is intended to be used via browser, but may be frustrating for e-reader users who use PDF. (I was trying to publish print copy via amazon with permission of author)

continuation-mark-set->context

Line 124

@margin-note{The @racket[continuation-mark-set->context] procedure provides best-effort structured backtrace information.}

https://github.com/racket/racket/blob/158361441c0617ee9df91954cf3afbfebc37094a/pkgs/racket-doc/scribblings/guide/control.scrbl#L124

Please include any other relevant details

Interaction block

@interaction[
(with-handlers ([exn:fail?
                 (lambda (v)
                   ((error-display-handler) (exn-message v) v))])
  (car 17))
]

full page
Image

'Gutter' guidance from amazon kindle direct publishing:

Insufficient gutter. Books with 407 pages require at least 0.625" (15.875mm) for the gutter (inside margin) and at least 0.25" (6.35mm) for the outside, top and bottom margins.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with pkgs/racket-doc/scribblings/guide/control.scrbl at line 124 and reproduce the page using scribble/manual rendered to PDF. Compare the margin-note containing continuation-mark-set->context with the nearby @interaction example and inspect how the PDF handles the long identifier. Done means the margin note stays within the gutter, including on the referenced guide page.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.