|
| 1 | +# Racket Glossary |
| 2 | + |
| 3 | +This project hopefully will result in a glossary to be included in the |
| 4 | +[Racket](https://racket-lang.org/) documentation to help primarily Racket |
| 5 | +beginners and intermediate users understand Racket concepts and interactions |
| 6 | +between them. |
| 7 | + |
| 8 | +## Purpose |
| 9 | + |
| 10 | +- Give definitions of terms used in Racket and Scheme in general. |
| 11 | + |
| 12 | +- Help beginning and intermediate users understand terms encountered in the |
| 13 | + Racket documentation. Assume that readers are familiar with imperative |
| 14 | + programming, but not with functional programming, Scheme and Racket. |
| 15 | + Therefore, some entries may contain comparisons with related features in |
| 16 | + other programming languages. |
| 17 | + |
| 18 | +- Provide context. So some entries may have more content than you'd usually |
| 19 | + expect from a glossary. |
| 20 | + |
| 21 | +## Format |
| 22 | + |
| 23 | +I'd like to see this glossary end up in the Racket documentation, so eventually |
| 24 | +it needs to be converted to Racket's documentation language |
| 25 | +[Scribble](https://docs.racket-lang.org/scribble/). On the other hand, I think |
| 26 | +we should use a simpler format like Markdown for easier contributions until the |
| 27 | +content is good enough to be included in the Racket documentation. |
| 28 | + |
| 29 | +Ideally, it would be great if there was a tool to convert Markdown to Scribble |
| 30 | +automatically. I haven't found one yet. The open source go-to tool for text |
| 31 | +format conversions is [Pandoc](https://pandoc.org/), but while it supports |
| 32 | +different Markdown dialects as input formats, it currently doesn't support |
| 33 | +Scribble as output format. However, it should be possible to write a [custom |
| 34 | +Pandoc writer](https://pandoc.org/custom-writers.html) to support Scribble as |
| 35 | +an output format. That's something for a different project though. ;-) |
| 36 | + |
| 37 | +## Contributions |
| 38 | + |
| 39 | +At the moment, the file `glossary.md` contains only a list of terms to be |
| 40 | +included in the glossary. |
| 41 | + |
| 42 | +My current plan to build the glossary is: |
| 43 | + |
| 44 | +1. Get feedback on the selection of the terms. For example, is something |
| 45 | + missing? |
| 46 | +2. Convert the terms to headings and add some of my thoughts as stubs to build |
| 47 | + upon. |
| 48 | +3. Wait for contributors to offer pull requests. :-) |
| 49 | + |
| 50 | +## License |
| 51 | + |
| 52 | +See the file [LICENSE](./LICENSE). |
0 commit comments