https://docs.racket-lang.org/reference/sequences.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._in-range%29%29 The docs normally note when features are unsafe? or am I missing something here?

A function is unsafe when there is a precondition that is not checked, and it informally requires users to enforce this precondition themselves.

Stuff like in-range uses unsafe functions internally, but in-range itself checks preconditions in a way that internal calls will always satisfy the preconditions. Hence, in-range is not considered unsafe, even though it does use unsafe functions.

Thanks I did not know that!

How should I format procedure argument names in normal text in Scribble, i.e. outside defstruct? At the moment, I’m using @racket[...], but I wonder if there’s another convention.

@sschwarzer Maybe https://docs.racket-lang.org/scribble/scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._racketvarfont%29%29\|racketvarfont ?

Or better https://docs.racket-lang.org/scribble/scribble_manual_code.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._var%29%29\|var

I see in https://docs.racket-lang.org/scribble/scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._racketvarfont%29%29 : > racketvarfont […] > Like https://docs.racket-lang.org/scribble/scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._racketplainfont%29%29\|racketplainfont, but colored as a variable (i.e., an argument or sub-form in a procedure being documented). It mentions the argument usage explicitly, so probably that’s the way to go? (Unless I understood the context/meaning of “argument” wrongly.)

Oh dear … > (https://docs.racket-lang.org/scribble/scribble_manual_code.html#%28form._%28%28lib._scribble%2Fmanual..rkt%29._var%29%29\|var datum) > Typesets datum as an identifier that is an argument or sub-form in a procedure being documented. Now my confusion is complete. :thinking_face:

So the documentation suggests both racketvarfont and var for arguments? :wink:

Or is racketvarfont on a lower abstraction level, maybe also an internal use in var?

Well. I got confused, when I click on the link to racketplainfont where it says: > Applies the ’tt style to _pre-content_. Beware that _pre-content_ is https://docs.racket-lang.org/scribble/decode.html#%28def._%28%28lib._scribble%2Fdecode..rkt%29._decode%29%29\|decoded as usual, making https://docs.racket-lang.org/scribble/scribble_manual_code.html#%28def._%28%28lib._scribble%2Fmanual..rkt%29._racketplainfont%29%29\|racketplainfont a poor choice for typesetting literal code directly but useful for implementing code-formatting functions. So I looked further and found var.

I think you are right.

So I’m going to use var then, I guess.

We could dig up the definition of var, if it doesn’t work.

Some examples in the Scribble docs would be nice.

Ok, I read a bit of https://github.com/racket/racket/blob/master/pkgs/racket-doc/scribblings/reference/pairs.scrbl , and the file seems to use just @racket[...].

I don’t know if it’s handled differently in other files, i.e. whether this usage is consistent.

I think @racket[arg] works as long as the identifier is unbound. If it is bound, I think, it will be linked to … somewhere else.

Yes, I think if the @racket[...] argument is a procedure argument, but also the name of an argument of a procedure, @racket will probably link to the procedure, which will be confusing.

So probably it would actually be better to use var because even if racket may work initially, it may generate a wrong link if a procedure with the same name is added.

I use @racket[foo] if foo is one of the variables in the signature of what I’m documenting. In this case, it seems to display as a local variable, in italics and such. If I want to write something that’s displayed as a local variable but it isn’t one of the variables in the signature of what I’m documenting, I use @racket[_foo], which displays as a local variable foo.

This also works for compound things like @racket[(+ _foo 1)].

I also found https://docs.racket-lang.org/reference/notation.html . It doesn’t say what to use when in Scribble source code, but it’s a possibly helpful overview in which style which items should be typeset.

I’m using @examples from scribble/example . (There’s another @examples in scribble/eval.)

My code in the Scribble document is @examples[ #:eval helper-eval #:label "See the difference in this example:" (define my-tasks (string->tasks (string-join '("x Complete task" "Incomplete task") "\n"))) my-tasks (group-tasks my-tasks (list (task-group-spec 'asc 'completed? #f))) (group-tasks my-tasks (list (task-group-spec 'desc 'completed? #f)))] whose last part renders as > (group-tasks my-tasks (list (task-group-spec 'desc 'completed? #f))) (list (task-group "Completed" (list (task #t #f #f #f "Complete task" '() '() '()))) (task-group "Not completed" (list (task #f #f #f #f "Incomplete task" '() '() '())))) Note that the task-groups have the same structure, but because the representation of the second group, it’s distributed over several lines.

Is there a way to control when line breaks are used? (I haven’t found anything so far.) If yes, how? If not, is it possible (and how), as a workaround, to typeset the example output “myself” instead of having it evaluated by Scribble?

It uses racket/pretty internally, so you might want to take a look at pretty-print-columns