Such a sensible syntax, right? The official ARM docs use it too. Not even sure who invented it, ARM or GAS. Anyway, that's another good reason to start with ARM.
There's also legacy ARMASM syntax that is barely worth mentioning.
ARM32 is much simpler to explain compared to ARM64. Registers are so much simpler, conditional execution is orthogonal, three-operand form is consistent. ARM64 made all the right practical choices, but has doubled the complexity. Still much better than x86 with its 10x complexity.
ARM32 is a gem, in my opinion. A truly simple instruction set, and easy to get your hands on with Raspberry Pi or emulation.
Yeah, and picking a language was the hardest decision for the book. I wrote the compiler prototype for it in OCaml, but using it for the book would have narrowed its audience unnecessarily. In the end, I'm very happy with picking TypeScript: it allowed to discuss the matters of static and dynamic typing within the same language. Using Python with mypy would be another option, but then, since I wanted the source language to be a subset of the implementation language, I would have to explain parsing whitespace-sensitive code, which is tricky.
In the book, lexing and parsing is done from scratch. I think tools like Flex and Bison are very handy, but for the book, my focus is on learning value.
About long options repeated: you can either specify "[options]" shortcut in a pattern in order not to put all options in that pattern, or you can have all options listed in the pattern--then you can avoid having them in option description.
About repeating program's name (say "naval_fate"), you can do:
It should be relatively easy to update it to work with 0.4; if you can make it work with 0.4 it would be great if you make a pull request to the project above.
When the DSL (http://docopt.org/) was designed, the main goal was just to formalise that pattern-language used for decades in man pages and `--help` screens. So variations that are conventional (such as `UPPER-CASE` for arguments or `<angular-brackets>` for arguments) are supported.
I'm also a fan of idea of using function-docstrings for separate subcommand help-screens. Problems: (1) exact API, (2) how to do that in non-python implementations. You (and everyone) is very welcome to suggest APIs for that in issues:
https://github.com/docopt/docopt/issues
There's also legacy ARMASM syntax that is barely worth mentioning.