docs - add examples and run spellcheck

[culix-7]

Thanks for creating asar. It is just excellent.

What do you think about adding a few examples to the docs to show how things work and make a few items more clear?
e.g. I added an example of creating a label based on another label plus some math, and added text explaining how math statements cannot use whitespace.
As a new user trying out the tool for the first time these behaviours weren't quite clear to me, so it might be nice to expand on them a bit.

I also fixed up a couple of variable names so they match the code block mentioned just above them, and ran spellcheck to fix a couple of words.

I'm happy to make these same edits in the version 2 manual if you want.

[culix-7]

A couple of questions:

1. I notice that a few places in the docs say "the output ROM", like Built-In Functions - https://rpghacker.github.io/asar/asar_2_beta/functions.html

Read one/two/three/four byte(s) from the output ROM

Is this actually reading from the output ROM? Should that say "input ROM" instead?

2. It looks like even after you make changes with asm code, the read() functions won't pick those up. What do you think about adding a sentence explaining that? How about something like:

Note that even after you write data with db or any other method, using the read() functions will not pick up or detect any changes you made.
This is because Asar is a multi-pass assembler: it reads your code and scans the file multiple times to calculate and fill in variables, labels, definitions, and apply changes before actually writing the file to disk.

[Alcaro]

Asar is primarily a patcher, so yes, input and output ROM are the same.

And yes, as you said, readN() only cares about the original input bytes. Having it read its output would yield too much potential for self-contradictory or otherwise impossible patches, like

org $008000
if read1($008000) == $40
db $80
else
db $40
endif

[p4plus2]

For what it's worth, we are looking at splitting this. So changing that to input rom (or maybe source rom?) would be more clear.

[culix-7]

Thank you for the replies. Okay, I can go change a few occurrences of 'input ROM' -> 'output ROM' if that is helpful.

[culix-7]

Overall the manual looks good. Great work on writing it.

There are two other things I could edit if you want:

1. Consistent warning format for deprecated features. The rep command says "Warning: this command is deprecate", and warnpc says "DEPRECATED". I could make these the same.
2. Convert <br/> html tags with a trailing slash to just regular <br> with no slash. The html validator at https://validator.w3.org/ says "Trailing slash on void elements has no effect and interacts badly with unquoted attribute values". It looks like they suggest just using <br>. I can easily clean this up if you want. There are 121 of them, so it might just make the diff look a bit ugly.

Or let me know if there is anything else you want edited or fixed.

[culix-7]

Okay I removed the trailing slashes, but that makes the diff pretty large and ugly. I don't know about you but I find that difficult to read and see the actually important changes.

Let me remove those commits from this PR and I can put them into a separate PR.

[culix-7]

Okay I removed the two commits. This should be much more readable now. Putting the 'trailing-slash' changes into their own PR will look like this: culix-7#1 . I can follow up with that after if you like.

I would consider this PR done and good enough for now, but let me know if you want anything else.