Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Use terminology more consistently #264

Open
gilch opened this issue Aug 22, 2024 · 0 comments · May be fixed by #265
Open

Use terminology more consistently #264

gilch opened this issue Aug 22, 2024 · 0 comments · May be fixed by #265
Labels
docs Explanation

Comments

@gilch
Copy link
Owner

gilch commented Aug 22, 2024

I understand the concepts well enough to use Hissp, but communicating them is hard. I've started a glossary page on the wiki, and apparently some of the boundaries are muddied. This should probably be moved into the Sphinx docs.

Lissp compiles in stages. Lissp -> Hissp -> Python. That's typically token -> atom -> literal, for individual elements, but tags and macros complicate the picture. Often all three stages want to use the same name for a thing, since it represents the equivalent concept in the next stage. But in some cases, the distinction matters. Multiple token types read as str atoms, and str atoms can compile to any Python. Control words are str atoms, but are treated almost like a distinct type by the compiler.

I also want to use terminology that's consistent with other Lisps, but Lisp dialects aren't totally consistent with each other either, and that shouldn't come at the cost of clarity.

The glossary should help me nail down definitions so I can use the terms consistently in the docs, in the source code, and in the wiki. We're not there yet. Unfortunately, GitHub's Markdown dialect doesn't support definition lists, so I'm pretty much writing it in HTML. ReStructuredText is probably better at this.

@gilch gilch added the docs Explanation label Aug 22, 2024
@gilch gilch linked a pull request Aug 25, 2024 that will close this issue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Explanation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant