Skip to content

Commit f560d08

Browse files
committed
Add README.md and LICENSE
1 parent f226812 commit f560d08

File tree

2 files changed

+57
-0
lines changed

2 files changed

+57
-0
lines changed

LICENSE

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
This glossary is licensed under the same terms as Racket, see
2+
https://github.com/racket/racket/blob/master/LICENSE.txt
3+
4+
If you want to contribute, make sure that you have the necessary
5+
rights to add your contributions under these Racket licenses.

README.md

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
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

Comments
 (0)