racket / racket/scribble

Empty lines for grouping in `scribble/example` `@examples`

Open
#331 0 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

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 semicolon
  • code:blank and (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 #f for 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

  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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.