# Racket glossary
**URL:** https://racket.discourse.group/t/racket-glossary/916
**Category:** General
**Tags:** glossary, learning-racket
**Created:** [April 22, 2022, 6:34pm UTC](https://racket.discourse.group/t/racket-glossary/916 "2022-04-22T18:34:08Z")
**Posts on this page:** 20
**Page:** 2
### Author:  [@sschwarzer](https://racket.discourse.group/u/sschwarzer)
#### Post date: [May 18, 2022, 9:46am UTC](https://racket.discourse.group/t/racket-glossary/916/21 "2022-05-18T09:46:15Z")
@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](https://racket.discourse.group/t/racket-glossary/916/18) 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.
---
### Author:  [@sschwarzer](https://racket.discourse.group/u/sschwarzer)
#### Post date: [July 26, 2022, 7:16pm UTC](https://racket.discourse.group/t/racket-glossary/916/22 "2022-07-26T19:16:39Z")
Here's some news on the Racket glossary. 🙂
- 37 % of the "basic" entries (and 20 % of the entries overall) are done:
- I published the glossary [on the Racket package server](https://docs.racket-lang.org/racket-glossary/index.html). 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](https://sourcehut.org/). Here's the [project page](https://sr.ht/~sschwarzer/racket-glossary/) with [code](https://git.sr.ht/~sschwarzer/racket-glossary), [tickets](https://todo.sr.ht/~sschwarzer/racket-glossary) - and a [mailing list](https://lists.sr.ht/~sschwarzer/racket-glossary) (more below).
- I updated the [information on contributions](https://git.sr.ht/~sschwarzer/racket-glossary#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. 🙂 You don't need to register with the mailing list to send mails.
---
### Author:  [@countvajhula](https://racket.discourse.group/u/countvajhula)
#### Post date: [July 30, 2022, 10:51pm UTC](https://racket.discourse.group/t/racket-glossary/916/23 "2022-07-30T22:51:44Z")
Brilliant, from looking at the terms covered, this looks like it will be a very useful resource.
---
### Author:  [@spdegabrielle](https://racket.discourse.group/u/spdegabrielle)
#### Post date: [April 12, 2023, 1:53pm UTC](https://racket.discourse.group/t/racket-glossary/916/24 "2023-04-12T13:53:52Z")
TIL 'Staged metaprogramming'
Is this a good one to add to the Racket Glossary?
I think [[PADL’23] Modern Macros](https://racket.discourse.group/t/padl23-modern-macros/1805) 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](https://twitter.com/lexi_lambda/status/1645889624617672704?s=20)
---
### Author:  [@sschwarzer](https://racket.discourse.group/u/sschwarzer)
#### Post date: [April 12, 2023, 2:48pm UTC](https://racket.discourse.group/t/racket-glossary/916/25 "2023-04-12T14:48:55Z")
> [@spdegabrielle](#):
>
> TIL 'Staged metaprogramming'
>
> Is this a good one to add to the Racket Glossary?
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.
---
### Author:  [@spdegabrielle](https://racket.discourse.group/u/spdegabrielle)
#### Post date: [April 12, 2023, 3:14pm UTC](https://racket.discourse.group/t/racket-glossary/916/26 "2023-04-12T15:14:20Z")
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.
---
### Author:  [@shawnw](https://racket.discourse.group/u/shawnw)
#### Post date: [April 13, 2023, 11:02am UTC](https://racket.discourse.group/t/racket-glossary/916/27 "2023-04-13T11:02:15Z")
> [@sschwarzer](#):
>
> Ideally, it would be great if there was a tool to convert Markdown to Scribble automatically. I haven't found one yet. The open source go-to tool for text format conversions is [Pandoc](https://pandoc.org/), but while it supports different Markdown dialects as input formats, it currently doesn't support Scribble as output format. However, it should be possible to write a [custom Pandoc writer](https://pandoc.org/custom-writers.html) to support Scribble as an output format. That's something for a different project though.
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.
---
### Author:  [@sschwarzer](https://racket.discourse.group/u/sschwarzer)
#### Post date: [April 13, 2023, 9:18pm UTC](https://racket.discourse.group/t/racket-glossary/916/28 "2023-04-13T21:18:13Z")
> [@shawnw](#):
>
> Did that ever happen?
Not that I know of.
> [@shawnw](#):
>
> There are Markdown parsers for Racket that would be easy to use for such a task...
I think [racket-commonmark](https://lexi-lambda.github.io/racket-commonmark/) is the best option. There are [two](https://docs.racket-lang.org/markdown/index.html) [other](https://docs.racket-lang.org/markdown-ng/index.html) Markdown parsers (the second seems to be a fork of the first) which don't seem to support CommonMark.
> [@shawnw](#):
>
> no need to get Pandoc involved.
You could also see it the other way around: If you add a Pandoc writer, there's no need to get Racket involved. 😉 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. 🙂
---
### Author:  [@shawnw](https://racket.discourse.group/u/shawnw)
#### Post date: [April 15, 2023, 5:21am UTC](https://racket.discourse.group/t/racket-glossary/916/29 "2023-04-15T05:21:40Z")
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.
---
### Author:  [@sschwarzer](https://racket.discourse.group/u/sschwarzer)
#### Post date: [April 15, 2023, 9:23pm UTC](https://racket.discourse.group/t/racket-glossary/916/30 "2023-04-15T21:23:38Z")
> [@shawnw](#):
>
> IIRC, Pandoc uses Lua for extensions.
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.
> [@shawnw](#):
>
> I know what language I'd rather use given the choice between it and Racket.
Yes, that may also enter into the tradeoff (for an individual). 😉
> [@shawnw](#):
>
> 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.
Which ones do you mean in particular? Generally, I think the [nested](https://docs.racket-lang.org/scribble/base.html#%28def._%28%28lib._scribble%2Fbase..rkt%29._nested%29%29) function should be useful to achieve something usable.
---
### Author:  [@shawnw](https://racket.discourse.group/u/shawnw)
#### Post date: [April 16, 2023, 12:57pm UTC](https://racket.discourse.group/t/racket-glossary/916/31 "2023-04-16T12:57:13Z")
Yeah, `nested` got something serviceable for block quotes and code blocks. Uploaded to the Racket package server for anyone interested - [markdown-to-scribble](https://pkgd.racket-lang.org/pkgn/package/markdown-to-scribble)
---
### Author:  [@sschwarzer](https://racket.discourse.group/u/sschwarzer)
#### Post date: [April 16, 2023, 6:58pm UTC](https://racket.discourse.group/t/racket-glossary/916/32 "2023-04-16T18:58:14Z")
Nice, that was quick! 🙂
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.
---
### Author:  [@shawnw](https://racket.discourse.group/u/shawnw)
#### Post date: [April 16, 2023, 11:56pm UTC](https://racket.discourse.group/t/racket-glossary/916/33 "2023-04-16T23:56:43Z")
> [@sschwarzer](#):
>
> I'm testing the conversion now and added so far one issue for the Github repo.
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.
> [@](#):
>
> 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.
I just open the file in DrRacket and use its "Scribble HTML" button, which converts it and opens it in a browser for you.
---
### Author:  [@benknoble](https://racket.discourse.group/u/benknoble)
#### Post date: [April 17, 2023, 12:48pm UTC](https://racket.discourse.group/t/racket-glossary/916/34 "2023-04-17T12:48:04Z")
> [@sschwarzer](#):
>
> 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.
If I understand you correctly, you want to add `#:style manual-doc-style` to your call to `title`.
---
### Author:  [@sschwarzer](https://racket.discourse.group/u/sschwarzer)
#### Post date: [April 17, 2023, 1:14pm UTC](https://racket.discourse.group/t/racket-glossary/916/35 "2023-04-17T13:14:14Z")
> [@benknoble](#):
>
> If I understand you correctly, you want to add `#:style manual-doc-style` to your call to `title`.
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.
---
### Author:  [@sschwarzer](https://racket.discourse.group/u/sschwarzer)
#### Post date: [April 17, 2023, 1:19pm UTC](https://racket.discourse.group/t/racket-glossary/916/36 "2023-04-17T13:19:48Z")
> [@shawnw](#):
>
> I just open the file in DrRacket and use its "Scribble HTML" button, which converts it and opens it in a browser for you.
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. 🙂
---
### Author:  [@benknoble](https://racket.discourse.group/u/benknoble)
#### Post date: [April 17, 2023, 1:42pm UTC](https://racket.discourse.group/t/racket-glossary/916/37 "2023-04-17T13:42:24Z")
> [@sschwarzer](#):
>
> 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.
Right; the solution with `@title[#:style manual-doc-style]{Your title…}` has solved that for me in the past.
---
### Author:  [@countvajhula](https://racket.discourse.group/u/countvajhula)
#### Post date: [April 17, 2023, 8:04pm UTC](https://racket.discourse.group/t/racket-glossary/916/38 "2023-04-17T20:04:06Z")
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:
```scheme
/* 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.
---
### Author:  [@sschwarzer](https://racket.discourse.group/u/sschwarzer)
#### Post date: [April 18, 2023, 12:39pm UTC](https://racket.discourse.group/t/racket-glossary/916/39 "2023-04-18T12:39:31Z")
> [@countvajhula](#):
>
> ```scheme
> /* This file is used by default by all Scribble documents.
> See also "manual.css", which is added by default by the
> `scribble/manual` language. */
>
> ```
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,
```scheme
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).
> [@countvajhula](#):
>
> 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.
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.)
---
### Author:  [@benknoble](https://racket.discourse.group/u/benknoble)
#### Post date: [April 18, 2023, 2:53pm UTC](https://racket.discourse.group/t/racket-glossary/916/40 "2023-04-18T14:53:13Z")
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/](https://benknoble.github.io/blog/2020/08/06/stop-sed-i/)
[Previous page](https://racket.discourse.group/t/racket-glossary/916.md?page=1)
[Next page](https://racket.discourse.group/t/racket-glossary/916.md?page=3)