Update docs for 0.15.0

Question

Update docs for 0.15.0

Closed this issue 4 years ago · 11 comments

Check the changelog for what still needs updating; it's kept up to date during development.
Update the This document is up-to-date for vx.x.x tags.

Answer 1 · 2021-05-15T11:35:31.000Z

This should be pretty much done as of cef82ca, but I'm keeping this open for a couple more days in case I think of anything I've missed.

Answer 2 · 2021-05-29T01:50:19.000Z

A-ha! The macro xmas tree needs to be better documented.

Right now we say in which order the syntax transformations of the block macros should run, but that doesn't mean it's the correct ordering for the macro invocations in the with ... header, since some (but not all) of the macros expand inside-out.

The documentation does already mention this caveat, but it would be nice to have a second xmas tree that gives the actual ordering the macro invocations should be put in a with ... header.

Until this is fixed, there are a few valid combo examples in the dialects, and some more can be hunted down from the macro unit tests. The general method to determine the ordering is noted in the docs, but involves looking at source code.

Answer 3 · 2021-06-03T09:33:08.000Z

Add to readings:

http://www.p-cos.net/lisp/guide.html
https://legacy.cs.indiana.edu/~dyb/pubs/monadicDC.pdf
- Particularly approachable explanation of delimited continuations.
- Could try building that for unpythonic in a future version. While our outermost call_cc already somewhat acts like a prompt, we're currently missing the ability to set a prompt wherever (inside code that already uses call_cc somewhere) and terminate the capture there. So what we have right now is something between proper delimited continuations and classic whole-computation continuations - not really co-values, but not really delimited continuations, either.
https://github.com/manuel/wat-js
- https://github.com/piokuc/pywat
- http://axisofeval.blogspot.com/2013/05/green-threads-in-browser-in-20-lines-of.html
- This suggests building proper delimited continuations shouldn't be that hard in Python.
https://dreamsongs.com/Separation.html
- Lisp-1 vs. Lisp-2.
https://github.com/cgyarvin/urbit/blob/master/doc/book/0-intro.markdown#hoon
- Some days I wonder if unpythonic even makes any sense, and then I happen to run into something like hoon. From the doc linked above:
  
  So we could describe Hoon as a pure, strict, higher-order typed functional language. But don't do this in front of a Haskell purist, unless you put quotes around "typed," "functional," and possibly even "language." We could also say "object-oriented," with the same scare quotes for the cult of Eiffel.
  
  While I am not sure if I will ever use hoon, it is hard not to like a language that puts quotes around "language". Few languages go that far in shaking up preconceptions. Critically examining what we believe, and why, often leads to useful insights. So, what do we have here?
  
  The claim hoon is not a language, but a "language", fully makes sense after reading some of the documentation. hoon is essentially an ab initio language with an axiomatic approach to defining its operational semantics, similarly to how Arc approaches defining Lisp. Furthermore, hoon is the functional equivalent of C to the underlying virtual assembly language, nock. From a certain viewpoint, the "language" essentially consists of glorified Nock macros. And glorified assembly macros are pretty much all a low-level HLL essentially is.
  
  Nock is a peculiar assembly language. The instruction set is permanently frozen, as if it was a physical CPU chip. Opcodes are just natural numbers, 0 through 11, and it is very minimalistic. For example, there is not even a decrement opcode. This is because from an axiomatic viewpoint, decrement can be defined recursively via increment. At which point, every systems programmer objects, rightfully, that no one sane actually does so. Indeed, the hoon standard library uses C FFI to take advantage of the physical processor's instruction set to perform arithmetic operations. Each piece of C code used for such acceleration purposes is termed a jet.
  
  Since - by the fact that the programmer called a particular standard library function - the system knows we want to compute a decrement (or a multiplication, a power, maybe some floating point operation, etc.), it can accelerate that particular operation by using the available hardware.
  
  The important point is, you could write out a nock macro that does the same thing, only it would be unbearably slow. In the axiomatic perspective - which is about proving programs correct - speed does not matter. At the same time, FFI gives speed for the real world.
  
  To summarize; as someone already put it, hoon offers a glimpse into an alternate universe of systems programming, where the functional camp won. It may also be a useful tool, or a source for further unconventional ideas - but to know for sure, I will have to read more about it.
  
  NOTE: Using natural numbers for the opcodes at first glance sounds like a Gödel numbering for the program space; but actually, the input to the VM contains some linked-list structure, which is not represented that way. Also, any programming language imposes its own Gödel numbering on the program space. Just take, for example, the UTF-8 representation of the source code text (which, in Python terms, is a bytes object), and interpret those bytes as one single bignum.
  
  Obviously, any interesting programs correspond to very large numbers, and are few and far between, so decoding random numbers via a Gödel numbering is not a practical way to generate interesting programs. Genetic programming works much better, because unlike Gödel numbering, it was actually designed specifically to do that. GP takes advantage of the semantic structure present in the source code (or AST) representation.
  
  The purpose of the original Gödel numbering was to prove Gödel's incompleteness theorem. In the case of nock, my impression is that the opcodes are natural numbers just for flavoring purposes. If you are building an ab initio software stack, what better way to announce that than to use natural numbers as your virtual machine's opcodes?
  
  From the standard library:
```
++  doos                                              ::  sleep until
            |=  hap=path  ^-  (unit ,@da)
            (doze:(wink:(vent bud (dink (dint hap))) now 0 (beck ~)) now [hap ~])
::
```
  The Lisp family (particularly the Common Lisp branch) has a reputation for silly terminology, but hoon takes that a step further.
  
  However, I think I will adopt the verb bunt, meaning to take the default value of. That is such a common operation in programming that I find it hard to believe there is no standard abbreviation.
  
  Judging by the docs, hoon is definitely ha-ha-only-serious, but I am not sure of whether it is serious-serious. It does advertise itself as the functional-programming equivalent of C. See the comments to the entry on Manuel Simoni's blog - some people do think hoon is actually useful.
  
  So maybe there is a place for unpythonic, too.
- The development of urbit has moved to a new repository. The latest hoon docs.
  - Interestingly, hoon has uniform support for wide and tall modes; it does not use parentheses, but uses a single space (in characteristic hoon fashion, termed an ace) versus multiple spaces (respectively, a gap). "Multiple spaces" allows also newlines, like in LaTeX.
  - hoon does not have syntactic macros. The reason given in the docs is the same as sometimes heard in the Python community - having a limited number of standard control structures, you always know what you're looking at.

Answer 4 · 2021-06-06T23:23:33.000Z

As of e9f0243, the xmas macro combo doc is done.

So it seems the last things to do before releasing 0.15.0 are:

~~Update doc/readings.md based on the above material.~~ a60a386.
~~Maybe move essays (at least What belongs in Python and the above piece on hoon) into a separate file.~~ 529357d.
Scan docs once more for wording and tone. @aisha-w did a great job for the docs in 0.14.2. The tone should be preserved in new material.
Remove the coming soon notice from README.md.

Answer 5 · 2021-06-14T21:36:42.000Z

This is a big documentation update, still ongoing; as of 5b0b61b, about 70% of features.md has been reviewed and updated.

Once that file is done, the major remaining effort is to update macros.md.

Answer 6 · 2021-06-16T23:15:08.000Z

As of 54e3fce, at 87% of features.md.

Answer 7 · 2021-06-17T23:29:15.000Z

As of ad535ee, 100% of features.md done.

Answer 8 · 2021-06-18T00:06:46.000Z

As of 78643c7, 20% of macros.md done.

At least the section on let constructs didn't need that many updates, after I'd already updated it once after upgrading the code.

Answer 9 · 2021-06-21T15:50:39.000Z

As of e0ccd1c, 92% of macros.md done. This will be finished soon!

Answer 10 · 2021-06-22T08:13:14.000Z

As of 2c30a69, 100% of macros,md done.

Answer 11 · 2021-06-22T08:14:11.000Z

As of 5c5b682, coming soon notice removed from README. This is finally done!