Improve documentation for readme sections: 'difference to clojure' , 'missing functionality'

[hgkamath]

Firstly, thank you to developer(s) of this project for their contributions.

I was reading the 'differences to clojure' and 'missing functionality' sections in the readme.

I think the write-up could be improved and made more informative if the bullet-lists were subdivided (or marked) to differentiate between design choices and feature-catch-up.

• Development catchup: Gives user hope that listed feature will one day be implemented.
  • Some points will have to be marked as a feature catchup: still in development, partial development or deferred to later. Meaning, that as of now they haven't been implemented but the intention is that one-day they will be.
• Intentional Design Divergence and feature omission: informs user to take design variance into consideration, not to expect catch-up.
  • Some points will have to be marked as design difference due to the fact they cannot be implemented the same way due to underlying language differences (rust vs java) or underlying binary runtime differences (native vs JVM)
  • Some points will have to be marked as intentional design difference, as you have decided it is superior to be implemented differently for rust.
  • Some points will have to marked as a jvm-clojure only feature that have no equivalent
• New feature by design: informs user of new possibilities and backward portability concerns.
  • Some points will have to be marked as a new feature that is possible on rust/native that isn't possible on JVM

Additionally, a 'state of the language' Specification file will provide a self-contained start-to-finish documentation of what the language (nanoclj) can do, but perhaps that should be filed as a different issue.

[rekola]

Excellent idea!

Currently, the section "Differences to Clojure" is mostly about design choices (e.g. Strings being UTF-8) or about missing features that are not very useful for an interpreter, and are therefore unlikely to be implemented (e.g. chunked lazy-sequences). The section "Missing functionality" contains features that could be potentially useful, and might be implemented at some point. It's not my intention to provide any new language features as such, and all the new features are mostly about the REPL, the standard library or C++ integration. Nevertheless, the new features are currently in the section "Features" along with features that are not actually new.

Are you suggesting, I should use the section labels you provided (Development Catchup, Intentional Design Divergence and Feature Omissing and New Features by Design) as such? I'm not very experienced in writing documentation, so any help is welcome.

Lastly, just to clarify, nanoclj is not written in Rust, but in C. There is another similar project called ClojureRS (https://github.com/clojure-rs/ClojureRS) that is written in Rust, and of course, there are two projects that also implement Clojure or ClojureScript in C/C++ (jank and planck). None of these other projects provide any advanced REPL capabilities, so they are not of interest to me.