I have two suggestions, which may improve the book.
1. It would be nice if the book would mention the fact that the CPUEmulator runs *a lot* faster if you choose "no animation". This information is especially useful for the Fill.asm project in chapter 4. I think as of now this information is only available on this forum.
2. In the section describing the syntax of .asm files, it would be nice to explicitly mention that inline comments, i.e. comments in the same line as instructions, are not supported. While the current description is correct and complete, I think assuming support for inline comments may be a common mistake. This is especially important because as of now, inline comments lead to a silent failure; the program simply won't load into ROM, without providing any pointers to the source of the problem.
If you run fill.asm with no animation then you can't easily confirm whether your program is working or not. The test script looks for some specific pixels being set or cleared, but this is a very weak test. If your code fails the test it definitely has issues, but it can be seriously wrong and still pass the test.
End of line comments ARE supported. They start with two forward slashes and end at the end of the line. The specification for comments (in the 1ed, I don't have 2ed yet) is:
Comments: Text beginning with two slashes (//) and ending at the end of the line is
considered a comment and is ignored.
This applies to text following an instruction.
The examples in the book are littered with end-of-line comments on the same line as instructions.
I got back to this issue after some time and I think we might have a misunderstanding here with regards to the "no animation" option. When the option "no animation" is selected, the screen is still animated, i.e. it's still possible to confirm that fill.asm is working by holding a key and seeing if the screen turns black.
In fact, the Fill.tst script now actively asks the user to ""Make sure that 'No Animation' is selected." so this issue seems to be resolved.
I'm currently reading the 2nd edition of the book, so this could be a possible source for our misunderstanding.