# Contributing

This chapter concerns the writers of this tutorial. When writing, there are a few standards to follow in order to maximize consistency throughout the tutorial.

## Address explanations

This section concerns the way addresses are written, as to avoid confusion.

### Direct page

* For the sake of simplicity and explanation, all direct page addresses ("`$xx`") shall use address `$7E0000` as its base. This shall be emphasized in code block comments, as well as explanations.

Example:

```
LDA #$42
STA $08            ; Store the value $42 into address $7E0008
```

### Absolute addressing

* All absolute addresses ("$xxxx") use address `$7E0000` as its base, if the address is between $0000-$7FFF inclusive. For addresses between $8000-$FFFF, address `$000000` shall be used as its base instead. This shall be emphasized in code block comments, as well as explanations.

Example:

```
LDA $8002            ; Load the value at address $008002 into A
STA $1008            ; Store that value into address $7E1008
```

## Styling

This section concern the styling of the document.

### Inline code

* All opcodes and instructions shall be surrounded by the markdown backtick (\`), regardless of the context.

Example: The opcode `LDA` is used to load values into the A register. Thus, `LDA #$49` loads the value $49 into A. This then can be increased to the value $4A by using `INC A`.

### Markdown tables

* Sentences and phrases within table cells generally shouldn't end with a period.
* Tables introducing opcodes should have the opcodes in **bold** and have at least the three columns in below example:

| Opcode  | Full name             | Explanation         |
| ------- | --------------------- | ------------------- |
| **LDA** | Load into accumulator | Load a value into A |

## Terminology

This section concerns the usage of certain words in certain context.

| Rule                                                                                                                               | Example                                                  |
| ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| When referring to the `Ricoh 5A22` processor, use `the SNES` instead                                                               | `The SNES` is capable of entering 8-bit or 16-bit mode   |
| When referring to a specific area in the SNES memory, always prepend `address` to it, preferably with the memory area (i.e. `RAM`) | (The) `RAM address` $7E0000 contains \[...]              |
| When referring to the accumulator (A) or the index registers (X and Y), just use `A`, `X` or `Y`                                   | `A` is now in 8-bit mode. `X` is used to index addresses |
| When referring to values, always prepend `value` to it                                                                             | A contains the `value` $00                               |

## Example codes

* Code shall use indentation when there are labels, sublabels or plus/minus labels on the same line as an instruction. The amount of indentation equals the length of the longest aforementioned type of label in the code block, including colon ("`:`"), plus two additional spaces.
  * Code shall use whitespace for indentation, not tabs.
* Opcodes are written entirely in uppercase (e.g.: `LDA`).
* Labels are written in PascalCase (e.g.: `Label1:`).
* Sublabels are written entirely in lower, underscore-case and the name should semantically suit the parent label, without redundancy (e.g.: `.return`).
* Defines are written in PascalCase (e.g.: `!SomeDefine`).
* Direct data (`db`, `dw`, `dl`, `dd`), indexers (`,x`, `,y`, `,s`) and opcode length specifiers (`.b`, `.w`, `.l`) are written entirely in lowercase.
* Comment indicators (i.e. `;`) shall start on column 20, and left-padded by whitespace, not tabs.
  * If there's no space for a comment on column 20, it should start on the same line anyway.
* In fact, never use tabs.
* Comment indicators shall be followed by a whitespace, before the comment itself.
* There will be an extra new line after the opcodes `RTS`, `RTL`, `RTI`, `JMP`, `JML`, `BRA`, `BRL`.
* These are guidelines which are to be followed as strictly as possible, but there may be exceptional cases. Use your best judgment.

Examples:

```
SomeLabel:         ; This label is on its own line
LDA.b #$42
STA $00            ; This is a comment
RTS

.table:
db $01,$02,$03,$04 ; Another comment

.second_table:
db $01,$02,$03,$04,$01,$02,$03,$04 ; An exceptional comment
```

```
TestLabel:  LDA #$02 ; This label is on the same line as an instruction
            STA $01
            BNE +
            NOP
+           RTS      ; The code is indented according to "TestLabel", not "+"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ersanio.gitbook.io/assembly-for-the-snes/contributing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.