Add clarification to syntax used in GBZ80(7) when a specific register is required

[brainard52]

Examples: LDH [C], A LD [HL], r8

The documentation includes symbols that aren't explained. For example, it's assumed that the reader will know what square brackets indicate. This knowledge should be readily available. I suggest adding a couple thoroughly-explained examples below the legend which cover each of the different syntax for the documentation. You could call it "Comprehending this document" or something.

[ISSOtm]

The brackets are part of the instruction's syntax, so no prior knowledge is assumed: they're explained by the instruction's description.

[brainard52]

I'll use LD [HL], r8 as an example.

"Store value in register r8 into byte pointed to by register HL."

This says that HL holds an address. It implies that the brackets de-reference the address, but this is never explicitly explained anywhere. This leaves ambiguity and room for confusion for somebody who is expected to read this but doesn't have prior knowledge of the specifics of the syntax presented.

[ISSOtm]

I think this is a problem of the document's intent. I believe gbz80(7) is intended as an instruction quick reference, i.e. it's intended for programmers already seasoned to RGBASM's syntax, but needing a quick refresher on what a given instruction does.

This issue seems to imply the document should instead be a learning resource; I disagree with that, as there is actually nothing fully explaining RGBASM's syntax, even rgbasm(5) omits some basic concepts. They are only meant as manual pages, not outright tutorials; and while there is definitely a lack of those, I don't think RGBDS' online docs are a good fit for that.

[Rangi42]

It doesn't imply that brackets dereference the address: it outright states that for this particular instruction, LD [HL], r8 "store[s] value in register r8 into byte pointed to by register HL".

It's true that every instruction follows that syntax pattern of using brackets to indicate a dereference, but it didn't have to be that way: they could have arbitrarily required LD A, *BC and LD A, DEREF DE for those particular opcodes.

I agree that things like "brackets indicate a dereference" belong in a separate tutorial, along with further detail like explaining what a dereference is, explaining the Game Boy memory map, analogies to pointers in C, etc.

[ISSOtm]

Closing, then.