Multi-id defform: hidden ids inflate whitespace
Nobody has claimed this yet.
- Dominant language
- Racket
- Stars
- 250
- Forks
- 102
- Avg merge
- 11d 11h
- Merged PRs (30d)
- 1
Description
defform was updated in 1b40fc8 to allow a single defform to serve as the link target for multiple identifiers, allowing it to document new forms that might create multiple bindings, similar to defstruct.
When a defform's #:id [(id ...) ids-expr] lists identifiers that do not appear in the form datum, they are attached to the first defining instance in the datum. Two visible effects follow:
-
With link targets on, the extra ids are not displayed, but their width is still counted when the following lines of a multi-line form are positioned. Every continuation line is pushed right by the combined length of the hidden ids.
-
With
#:link-target? #f, the extra ids are typeset visibly, they all get run together after the first id with no separators.
The single-id mode, and the multi-id mode where every listed id appears in the datum, render correctly.
Given a things.rkt…
#lang racket/base
(provide point point? point-x point-y)
(define-syntax-rule (point . _) (void))
(define (point? v) #t)
(define (point-x p) 0)
(define (point-y p) 0)
…The following mve.scrbl file:
#lang scribble/manual
@(require (for-label racket/base "things.rkt"))
@defmodule["things.rkt" #:packages ()]
@defform[#:link-target? #f
#:id [(point) (list #'point)]
(define-thing point (x
y))]{
Control: every listed id appears in the form. Continuation line is indented
correctly.
}
@defform[#:id [(point point? point-x point-y) (list #'point #'point? #'point-x #'point-y)]
(define-thing point (x
y))]{
Continuation line is indented by an extra 20 characters, the combined length
of @racket[point?], @racket[point-x] and @racket[point-y].
}
@defform[#:link-target? #f
#:id [(point point? point-x point-y) (list #'point #'point? #'point-x #'point-y)]
(define-thing point (x
y))]{
Same as above with @racket[#:link-target? #f]: the ids that do not appear in
the form are typeset visibly, concatenated after the first one.
}
…renders with raco scribble --html mve.scrbl as:
In the first box, y is indented 21 columns. In the second and third boxes it is indented 41. The difference of 20 is point? (6) + point-x (7) + point-y (7).
Racket v9.3, scribble-lib 1.65.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Run raco scribble --html mve.scrbl using the provided things.rkt and mve.scrbl reproduction, then trace the defform rendering and indentation behavior. Check both link-target modes. Done means hidden identifiers no longer affect continuation-line indentation, while visible extra identifiers are separated correctly.
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
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100