Empty lines for grouping in `scribble/example` `@examples`
Nobody has claimed this yet.
- Dominant language
- Racket
- Stars
- 250
- Forks
- 102
- Avg merge
- 11d 11h
- Merged PRs (30d)
- 1
Description
Sometimes I want to group lines in an @examples form, i.e. insert empty lines between groups of inputs and outputs.
Here's an example from the documentation of define-syntax to show what I mean:
Examples:
> (define-syntax foo
(syntax-rules ()
((_ a ...)
(printf "~a\n" (list a ...)))))
> (foo 1 2 3 4)
(1 2 3 4)
> (define-syntax (bar syntax-object)
(syntax-case syntax-object ()
((_ a ...)
#'(printf "~a\n" (list a ...)))))
> (bar 1 2 3 4)
(1 2 3 4)
However, since the foo and bar examples are independent, these examples would look clearer as
Examples:
> (define-syntax foo
(syntax-rules ()
((_ a ...)
(printf "~a\n" (list a ...)))))
> (foo 1 2 3 4)
(1 2 3 4)
> (define-syntax (bar syntax-object)
(syntax-case syntax-object ()
((_ a ...)
#'(printf "~a\n" (list a ...)))))
> (bar 1 2 3 4)
(1 2 3 4)
Note the empty line after the (foo 1 2 3 4) output.
I tried a lot to achieve this with scribble/example, but didn't succeed. Things that almost worked:
(code:comment "")still prints the semicoloncode:blankand(code:line)add a prompt in front of the otherwise empty line(eval:no-prompt code:blank)adds two or three empty lines(eval:no-prompt (code:line))gives an exception because(code:line)doesn't seem to be recognized inside(eval:no-prompt).(eval:no-prompt)adds a tiny gap. I was (kinda) able to get an "empty line" with a sequence of(eval:no-prompt), but that's quite a dirty hack, isn't it? ;-)- Split the
@examples[...]invocations into several, one for each group. This requires#:label #ffor the groups after the first and duplication of possible setup / keyword arguments from the first@examples[...]of the group.
I found a few examples in the Racket documentation that do use empty lines as shown above, but they use mz-examples, or examples from the legacy scribble/eval module.
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
Start with the scribble/example @examples form and compare its behavior with mz-examples and the legacy examples from scribble/eval. Investigate how empty lines between independent input/output groups are represented, then verify that an empty line can appear without a prompt or extra spacing while preserving setup and keyword arguments.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100