search

h3rald / min

A small but practical concatenative programming language and shell
https://min-lang.org
MIT License
311 stars 23 forks source link

documentation #42

Closed zenon closed 4 years ago

zenon commented 4 years ago

Hello,

today I took the pleasure to play with min. Thank you for this, it's cool!

As that's the only moment to really read documentation, I did note about spelling issues, strangenesses and whatever. I hope this will help.

Kind regards, and thank you!

zenon

Notes about https://h3rald.com/min/Min_DeveloperGuide.htm Quotes in bold.

2.2 To exit min shell, press CTRL+C or type exit and press ENTER.

z: For exit to work, there needs to be an int on the stack. Suggested formulations:

3. .. Then, another list containing two symbols (dup and ) is pushed on the stack. This constitutes a quoted program which, when executed duplicates (dup) the first element on the stack and then multiplies () the two elements together.

z: It can be confusing whether the parens are mentioned or used. I mean, you talk about (dup *) [here i mention the parentheses :-)], and then you use several parentheses. Suggestion:

Then, another list containing two symbols, i.e. dup and , is pushed on the stack. This constitutes a quoted program which, when executed duplicates the first element on the stack -this is done by dup- and then multiplies -with - the two elements together.

Parentheses are grouped together one or more elements, so that they are treated as a single element and they are not evaluated immediately.

z: are grouped together -> are used to group together

Symbols can be used to perform operations on the whole stack.

z: Not clear. Does this introduce the concept of symbol? Do you mean: Symbols, also called words, refer to functions that operate on .. ?

3.1 Data Types

z: the type boolean seems to exist, but is missing.

z: The link to the dict module is broken

3.2.1 .. The synbol** z: (spelling) synbol -> symbol

.. while the symbol apply can be used to dequote a quotation by pushing its elements on a separate stack.

z: this needs some explanation. until now we only heard of one stack.

3.3 Operators .. Besides symbols, min provides a set of predefined sigils for commonly-used symbols.

z: I suggest an addition, like: Besides symbols, min provides a set of predefined sigils as abbreviation for commonly-used symbols.

z: In the sigil list, the links to dget, dset, dhas? are broken

*3.4 Definitions Being a concatenative language, min does not really need named parameters or variables: simbols just pop..

z: (spell) simbols -> symbols

3.4.1 Lexical scoping and binding

z: broken link to wikipedia

4.2 z: my windows computer doesn't have a HOMEPROFILE environment variable. It has USERPROFILE instead.

I didn'tread the reference yet. Except http; it'll get an extra issue.

h3rald commented 4 years ago

Excellent!!!! I have a terrible habit not to re-read what I write, and even when I do I just don't spot things sometimes.

I'll go through all this and improve the docs. Thanks again!

Out of curiosity, are you using the pre-built libraries or are you compiling min from source?

zenon commented 4 years ago

Good Morning!

I feel the need to add that nim is one of the rather well documented projects :-)

Prebuild unter windows.

Under Linux (more specific Debian Buster in its Windows Subssystem incarnation, don't ask :-) ) the prebuild did not work; some issues with the version of libc.so, it seems. So I built it myself, and that worked smoothly.

Kind Greetings!, z.

h3rald commented 4 years ago

Everything should be fixed now, thanks again!