What is the correct incantation for “raco scribble” to produce links to documentation on http://docs.racket-lang.org\|docs.racket-lang.org. In “flmatrix.scrbl” I have used @other-manual['math/matrix] to refer to the math/matrix manual and @tech{flonums} to refer to “flonums” (like [+]) does.

The following attempt is not enough:

raco scribble +m --redirect <http://docs.racket-lang.org/> flmatrix.scrbl &amp;&amp; open flmatrix.html

[+] https://docs.racket-lang.org/reference/flonums.html?q=double#%28def._%28%28lib._racket%2Fflonum..rkt%29._flvector%29%29

If you leave out --redirect, do you get local links? I ask because your raco scribble call looks ok, but other-manual needs a module path for the document “.scrbl” file, not the documented module, and tech will need a #:doc argument to reference another manual.

No local links either - and local links would be fine while I work on the manual.

I’ll try the path to the scribble document instead.

Now the reference to flonums works. It confused me that it was defined in “numbers.scrbl” but I needed to refer to “reference.scrbl”. In hind sight it makes sense.

Spoke too soon. The link looks fine, but clicking it I end up at: https://docs.racket-lang.org/?doc=reference&rel=numbers.html%23%2528tech._flonum%2529

Ah! Simply had to remove --redirect <http://docs.racket-lang.org/> and now I end up the correct place.

I think you’ll want --redirect-main instead of --redirect. If you use --redirect, you need a longer URL: <https://docs.racket-lang.org/local-redirect/index.html>

That worked. Thanks.

Although I haven’t thought about this super hard: A syntax-property for indent could be useful! However IIUC you’d need to fully-expand a module to discover that reliably? That means 1. You need a “fancy” editor like DrRacket or racket-xp-mode or a LSP server — i.e. you need to run Racket. That doesn’t help with simple text editors, where people might expect to be able to edit a language file and indent properly. 2. Even if you have a fancy editor/server, fully-expanding can be slow, and, syntax is often imported (and fully-expanding all imports can be slow, which is why we have e.g. bytecode).

All this makes me wonder if there ought to be some sort of concept of a “database” with information about imports. Such as indent. Definition site. Definition usages across some scope. Stuff like that.

Would it be stored in bytecode or bytecode-like separate files? Or in a sqlite db like doc xref (IIUC)? idk.

It might be both. Definition usages feels more like xref and sqlite? Whereas metadata about a definition like syntax indent feels “bytecode-y”?

/me is super hand-wavy

Are there any Linux that can confirm this?

Can confirm. There is a noticeable lag when using PLT_DISPLAY_BACKING_SCALE=1.5, but not when using PLT_DISPLAY_BACKING_SCALE=2. Linux version 5.6.13-arch1–1. Racket versions 7.7 BC and CS.

Maybe animations? Since I spent all that work making animated snips and all. I could put that into a package.

Yes

I think expansion is okay if it doesn’t have to happen every time. So after expansion, the indentation information could be “compiled” (serialized) into some sort of cache (either on disk or in memory).

I definitely lean more towards attaching metadata to definitions than to usages.

The latter seems unscalable and it won’t work with usages that don’t compile.

Yes! we need a 2020 Standard Fish Summer Picture Competition. - Need to work out some details;

Dates:???

Liberal rules it just needs to be racket or racket language related in some way • doesn’t have to use pict or racket/draw.

Can be ; • moving picture(gif/video), • animation or interactive animations. • Can be Sound or music (pictures for the ears)

categories there will be a range of categories to cover the variety, but will include • generative techniques, • waffle themed art, • visualisations, • inventive use of the plot package • ascii art. • submissions method; ? Some advice appreciated. (I was thinking a package or a PR but maybe that is too much?) • End date? • Announcement of winners (maybe at Racket con?)

@notjack better?

Can only skim it right now but I like it

What do you think about timing it for after the 7.8 release? Then the Scribble gif changes would probably be in, and I could send a pull request to add a pict/movie module to the main distribution that provides the animation snip implementation.

(when is the next release anyway)

July

https://github.com/racket/racket/wiki/Release-Calendar\|https://github.com/racket/racket/wiki/Release-Calendar

I agree about attaching metadata to definitions not usages. [I probably confused things by mentioning usages. The only connection is, “If we used a database for feature X, that reminds me, another feature Y could use that.” For now please forget I mentioned them. :simple_smile:]

To take back something else I said: A data specification for indent can work fine for langs using s-expressions. But I don’t see how that could support languages generally. The only API I can imagine for that, is the one where the lang — or now also syntax provided by a non-lang module — can supply a function and the tools must call it. Right?

I was thinking of something similar to the Rectangle Rule, which is what Google uses in their Java autoformatter https://github.com/google/google-java-format/wiki/The-Rectangle-Rule\|https://github.com/google/google-java-format/wiki/The-Rectangle-Rule

I think you’re right that the lang needs to be involved somehow. Maybe an autoformatter submodule similar to the reader submodule?

These are all good questions! I am quite busy right now, but there are a couple of points that I can quickly reply:

> As a possible alternative, what if indentation information were handled more like documentation — i.e. extracted as part of building, and stored in a “database”? So that tools and editors could access it without needing to instantiate, or even fully-expand, a module that defines it? IIUC, Racket’s documentation needs module to be fully expanded. Otherwise, the for-label mechanism wouldn’t work.

One possible way to specify the indentation configuration without expanding code is to write it in a comment. This is an approach that is used by non S-exp languages’s linters/type checkers to suppress errors.

Why comment? Well, if we use S-exp, then it could be the case that someone writes:

(define x (quote (indent 3))) and it would not be possible until expansion to know that the indent is meant to be quoted as a data rather than a description.

As a starting point, what if non-lang syntax could provide the same function that a lang could: https://docs.racket-lang.org/tools/lang-languages-customization.html#(part._.Indentation)

One thing about that I don’t love, assuming I understand it correctly, is that racket:text<%> is from the GUI framework. That feels too “heavy” for a little bit of syntax to require that just to specify some indent. (Also, honestly, it feels a bit heavy for tools like Emacs Racket Mode to need to require that.)

Also, although I don’t understand it very well, intuitively it seems that would also (a) need a 'color-lexer https://docs.racket-lang.org/tools/lang-languages-customization.html#%28part._.Syntax_.Coloring%29 — and (b) need that lexer to have run before the indenter is called? I think?

Maybe it would be possible to “tease out” some API that doesn’t presume the GUI framework, and that is more clear about how a lexer fits into the picture. And use that both for langs and for non-lang syntax indent.

(Is my latest fuzzy, hand-wavy idea.)

Also confirming on 7.6 running on gentoo.

Made my planning library’s block world example prettier by replacing it with an actual Sokoban level (https://en.wikipedia.org/wiki/Sokoban)

Yeah I think any autoformatting needs to be decoupled from the racket GUI framework. There’s lots of non-editor use cases for autoformatting. For instance, I’d really like to be able to run an autoformatter in a headless Docker container as part of a github action.