Racket glossary

General
,
21

@hendrikboom3 I see you replied by mail and if you interact with Discourse mainly/only per mail you probably didn't see my response earlier in the discussion, which has additional arguments regarding the wiki approach.

I was answering to your earlier message individually after answering to @benknoble , but Discourse encouraged me to edit my previous message to group replies instead of having several small ones. I see this approach isn't optimal for email-only participants.

22

Here's some news on the Racket glossary. :slight_smile:

  • 37 % of the "basic" entries (and 20 % of the entries overall) are done:

    Completion stats, ignoring cross references:

basic        |■■■■■■■■■■■■■■■■■■■·······························|  22 of  59 done
intermediate |■■■···············································|   2 of  34 done
advanced     |··················································|   0 of  25 done

total        |■■■■■■■■■■········································|  24 of 118 done

    (I wrote a small helper script that scans the Scribble file and prints the current statistics.)

  • I published the glossary on the Racket package server. My original plan was to publish the package when the "basic" category is mostly complete, but it's just awkward when talking with people about the project and tell them to clone and build the documentation.

  • Project hosting is now mainly on Sourcehut. Here's the project page with code, tickets - and a mailing list (more below).

    Pull requests on Github are still possible.

  • I updated the information on contributions. As long as the contributions are simple enough, I'm also fine with just sending feedback to the mailing list, so you don't even need to work with Git. :slight_smile: You don't need to register with the mailing list to send mails.

5 Likes
23

Brilliant, from looking at the terms covered, this looks like it will be a very useful resource.

2 Likes
24

TIL 'Staged metaprogramming'

Is this a good one to add to the Racket Glossary?

I think [PADL’23] Modern Macros provides more details, but doesn't use the term.

“Staged programming” refers to compilation models that allow a program to generate code that is then run at compile-time to produce a second program, after which the first program can be discarded. There are a few different approaches to providing language support for this.

Obviously, the simplest way is to just write a program that just writes another program to stdout. But this is pretty unpleasant in practice. Staged metaprogramming systems provide structured ways to do this that are integrated into the language and compiler.

The main approaches are Lisp-style macro systems, which allow arbitrary transformations on syntax trees to be executed at compile-time, and MetaML-style staged programming systems, which allow compile-time functions to generate expressions that are spliced into the program.

Staged metaprogramming allows you to write embedded DSLs that are effectively an extension of the host language’s compiler, so there is no need to do any processing on the embedded language’s syntax at runtime. In a sense, it is more tagless and more final than tagless final.

Source: @lexi.lambda https://twitter.com/lexi_lambda/status/1645889624617672704?s=20

2 Likes
25

Thanks for the suggestion.

I think this entry would be too special for the glossary. I'd say 'Staged metaprogramming" clearly belongs in the glossary's "advanced" level, and generally I'd like to keep that level to the stuff that comes in the Racket standard distribution or that Scheme/Racket learners are very likely to encounter in articles and discussions.

So concepts like continuations and custodians are going to be in the glossary (currently they only have stubs), but staged metaprogramming likely not.

26

Fair enough. It is not in the Guide or Reference as far as I can tell.

Maybe ‘staged metaprogramming’ is a term coined by @lexi.lambda ? (I quite like it - it is as precise and evocative as ‘macro’ is diluted)

S.

27

Did that ever happen? There are Markdown parsers for Racket that would be easy to use for such a task... no need to get Pandoc involved.

1 Like
28

Not that I know of.

I think racket-commonmark is the best option. There are two other Markdown parsers (the second seems to be a fork of the first) which don't seem to support CommonMark.

You could also see it the other way around: If you add a Pandoc writer, there's no need to get Racket involved. :wink: What I like about the Pandoc approach is that you'd get support for many other input formats for free, not just a specific Markdown dialect. (Now, you could work around this by converting from a Pandoc-supported input format to Markdown and then use a Markdown to Scribble converter in Racket, but that seems kind of convoluted to me.)

When I asked about a Markdown to Scribble converter I primarily had the Racket Glossary as use case in mind, but apart from that, inclusion in Pandoc makes more sense to me.

In the end, it depends on which tradeoff you prefer. :slight_smile:

29

IIRC, Pandoc uses Lua for extensions. I know what language I'd rather use given the choice between it and Racket.

It'd be a pretty straightforward task; just have to figure out how to represent all the different ATX header levels in Scribble, since there's more of them than subsection tags. Hmm. Might have a new project...

Edit: The various block quotes are the harder bit in practice; the core scribble/base lang doesn't seem to have any support for them.

30

I think so, but I guess you could also implement the writer in Haskell (Pandoc's "main language"). If you're not experienced with Haskell yet, this could be a hurdle, though.

Yes, that may also enter into the tradeoff (for an individual). :wink:

Which ones do you mean in particular? Generally, I think the nested function should be useful to achieve something usable.

31

Yeah, nested got something serviceable for block quotes and code blocks. Uploaded to the Racket package server for anyone interested - markdown-to-scribble

1 Like
32

Nice, that was quick! :slight_smile:

I'm testing the conversion now and added so far one issue for the Github repo.

I was about to report that code in backticks isn't formatted, but it turned out that it is converted to @tt{@literal{code}}, but I don't see this in an HTML file generated with scribble input.scrbl, probably due unavailable style information.

All: Is there a simple way to render a Scribble file to an HTML file that uses the formatting Racket packages use? I know I could add the Scribble file to the scribblings directory and update the info.rkt file, but it would be nice if there was an easier way, since this is just for experiments.

33

Thanks. I'm sure there's a lot of things to work out; it's still very much a work in progress to get everything looking right.

I just open the file in DrRacket and use its "Scribble HTML" button, which converts it and opens it in a browser for you.

1 Like
34

If I understand you correctly, you want to add #:style manual-doc-style to your call to title.

35

Sorry, I wasn't precise enough. I was referring to using the scribble command from the command line.

If I add the Scribble file generated by Shawn's tool to scribblings and run raco setup, the generated document has the style of the Racket documentation. When I process exactly the same file with scribble some-document.scrbl on the command line, the generated HTML, shown in the web browser, uses a much simpler design.

36

Thanks for the tip, I didn't know about this DrRacket feature.

Using DrRacket seems to give me the same styling as when running scribble the-file.scrbl on the command line.

By the way, I was only trying to use the Racket documentation format because the code markup didn't show in the generated document, so at first I thought this was a matter of different styles, so I wanted to try the Racket documentation style. Besides that, generating and inspecting a HTML file from a "plain" Scribble invocation IMHO makes a lot of sense to check the conversion under "minimum" conditions. :slight_smile:

37

Right; the solution with @title[#:style manual-doc-style]{Your title…} has solved that for me in the past.

1 Like
38

As Ben mentioned, it has something to do with whether the docs are built with "manual" style or default style. I recently noticed this comment in the default scribble.css file used by Scribble:

/* This file is used by default by all Scribble documents.
   See also "manual.css", which is added by default by the
   `scribble/manual` language. */

If you're using #lang scribble/base or #lang scribble/doc, changing it to #lang scribble/manual is another way to get it to use the "manual" style.

1 Like
39

I didn't find a manual.css file in the Racket distribution, but the three files manual-style.css, manual-racket.css and manual-fonts.css. When I use all three on the command line like this,

export RACKET_DIR=...
scribble \
  ++style $RACKET_DIR/share/pkgs/scribble-lib/scribble/manual-style.css \
  ++style $RACKET_DIR/share/pkgs/scribble-lib/scribble/manual-racket.css \
  ++style $RACKET_DIR/share/pkgs/scribble-lib/scribble/manual-fonts.css \
  glossary-notes.scrbl

I get the HTML file with the "manual" layout (as far as I can tell).

I was looking for a way to get the manual style without changing the Scribble file because (currently) Shawn's md2scrbl uses only #lang scribble/base and I didn't want to change the generated Scribble file for every run of the tool. (Although, at least on Posix systems, it would be possible to change the #lang in the generated Scribble file without editing it interactively, by using sed instead.)

40

Be careful using sed for in-place edits (though, since you mention POSIX, you probably already know that -i is unportable): https://benknoble.github.io/blog/2020/08/06/stop-sed-i/

1 Like