Skip to content

Commit 75b14b6

Browse files
authored
[main] Improve documentation (Polprzewodnikowy#179)
## Description Documentaion has been rewritten/improved/expanded in certain areas including typo and formatting fixes. ## Motivation and Context Tidier documentation, to make things a bit more dumb-proof for end users. ## How Has This Been Tested? Not applicable. ## Types of changes - [ ] Improvement (non-breaking change that adds a new feature) - [ ] Bug fix (fixes an issue) - [ ] Breaking change (breaking change) - [x] Documentation Improvement - [ ] Config and build (change in the configuration and build system, has no impact on code or features) ## Checklist: - [ ] My code follows the code style of this project. - [ ] My change requires a change to the documentation. - [x] I have updated the documentation accordingly. - [ ] I have added tests to cover my changes. - [ ] All new and existing tests passed. Signed-off-by: IlDucci <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Summary by CodeRabbit - **Documentation** - Updated documentation for initial SD card setup, menu controls, and menu customization. - Improved clarity and readability of instructions. - Refined section headings and formatting across multiple documentation files. - Added new sections explaining menu settings, ROM information, and control details. - Emphasized warnings regarding filename compatibility and save file issues. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent 9113d1c commit 75b14b6

File tree

4 files changed

+69
-59
lines changed

4 files changed

+69
-59
lines changed

docs/00_getting_started_sd.md

Lines changed: 32 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,41 @@
1-
## First time setup of SD card
1+
## Initial Setup of SD Card
22

3-
### Flashcarts
4-
Using your PC, insert the SD card and ensure it is formatted for compatibility with your flashcart.
5-
**warning** Filenames are expected to be part of the ASCII character set. Unicode characters are not fully supported and may cause a crash screen.
3+
### First Steps
4+
Connect the SD card to your PC and ensure it is properly formatted to be compatible with your flashcart.
5+
**WARNING:** Filenames are expected to be written in ASCII, with Western Europe characters fully compatible. Other Unicode characters, such as those from Eastern Europe, Russia, Asia or Middle East regions (to name just a few examples) are not fully supported and may not be displayed.
66

7-
#### SC64
7+
#### Preparations for SC64
88
- FAT32 and EXFAT are fully supported.
99
- An SD formatted with 128 kiB cluster size is recommended.
1010

11-
- Download the latest `sc64menu.n64` (assuming you are using an *sc64*) file from the [releases](https://github.com/Polprzewodnikowy/N64FlashcartMenu/releases/) page, then put it in the root directory of your SD card.
11+
- Download the latest `sc64menu.n64` file from the [releases](https://github.com/Polprzewodnikowy/N64FlashcartMenu/releases/) page, then put it in the root directory of your SD card.
1212
- Create a folder in the root of your SD card called `menu`.
13-
- Place your ROMs on the SD Card, in any folder (**except for `menu`**).
13+
- Place your ROM files on the SD card, **in any folder except `menu`**.
1414

15-
#### Other supported flashcarts
15+
#### Preparations for other supported flashcarts
1616
- FAT32 recommended.
17-
- An SD formatted with default cluster size is recommended.
17+
- An SD formatted with the default cluster size is recommended.
1818

19+
(TBW)
1920

2021

21-
### Emulator support
22+
### Emulator Support
2223
Emulators should be added to the `/menu/emulators` directory on the SD card.
2324

24-
Menu currently supports the following emulators and associated ROM file names:
25+
N64FlashcartMenu currently supports the following emulators and associated ROM file names:
2526
- **NES**: [neon64v2](https://github.com/hcs64/neon64v2/releases) by *hcs64* - `neon64bu.rom`
2627
- **SNES**: [sodium64](https://github.com/Hydr8gon/sodium64/releases) by *Hydr8gon* - `sodium64.z64`
27-
- **Game Boy** / **GB Color**: [gb64](https://lambertjamesd.github.io/gb64/romwrapper/romwrapper.html) by *lambertjamesd* - `gb.v64` / `gbc.v64` ("Download Emulator" button)
28-
- **SMS** / **GG**: [smsPlus64](https://github.com/fhoedemakers/smsplus64/releases) by *fhoedmakers* - `smsPlus64.z64`
28+
- **Game Boy**/**GB Color**: [gb64](https://lambertjamesd.github.io/gb64/romwrapper/romwrapper.html) by *lambertjamesd* - `gb.v64`/`gbc.v64` ("Download Emulator" button)
29+
- **SMS**/**GG**: [smsPlus64](https://github.com/fhoedemakers/smsplus64/releases) by *fhoedmakers* - `smsPlus64.z64`
2930
- **Fairchild Channel F**: [Press-F-Ultra](https://github.com/celerizer/Press-F-Ultra/releases) by *celerizer* - `Press-F.z64`
3031

3132

32-
### 64DD disk support
33-
For the ability to load and run 64DD disk images, you need to place the required 64DD IPL dumps in the `/menu/64ddipl` folder on the SD card.
33+
### 64DD Disk Support
34+
To load and run 64DD disk images, place the required 64DD IPL dumps in the `/menu/64ddipl` folder on the SD card.
3435
For more details, follow [this guide on the 64dd.org website](https://64dd.org/tutorial_sc64.html).
3536

3637

37-
#### So what would the layout of the SD Card look like?
38+
#### So what would the layout of the SD card look like?
3839
```plaintext
3940
SD:\
4041
@@ -61,37 +62,36 @@ SD:\
6162
├── (a rom).n64
6263
├── (some folder with roms)\
6364
│ └── (some folder with roms)\
64-
| └── (Some supported ROM files)
65+
| └── (some supported ROM files)
6566
66-
├── (Some supported ROM files)
67+
├── (some supported ROM files)
6768
|
68-
└── (Some folder with 64DD disk images)\
69-
└── (Some 64DD disk images)
69+
└── (some folder with 64DD disk images)\
70+
└── (some 64DD disk images)
7071
```
7172

7273

7374
## Save Files
74-
All save files (whether `FlashRam`, `SRAM` or `EEPROM`) use the `.sav` extension and match the filename of a ROM.
75-
76-
Each save file can be found in the `/saves` folder located in the **same directory** as the ROM and shares the same file name, apart from the extension.
77-
These files are created and modified when a "game" saves.
75+
All save files (whether `FlashRam`, `SRAM` or `EEPROM`) will be read from a `/saves` folder located **in the same directory as the ROM**
76+
and they must share the same file name, but use the `.sav` extension. `.sav` files will be created and modified whenever a ROM file saves to
77+
the "cartridge save memory".
7878

7979
```plaintext
8080
├── (some folder with roms)\
8181
├── a_rom.z64
82-
├── b_rom.n64
82+
├── b_rom_whatever.n64
8383
└── saves\
8484
├── a_rom.sav
85-
└── b_rom.sav
85+
└── b_rom_whatever.sav
8686
```
8787

88-
### Transfering saves from an ED64
89-
If transferring a file from a different flashcart, such as the ED64, it will be necessary to change the extension of the file to `sav`.
90-
91-
i.e. for `Glover (USA).eep` you would need to change the extension to `Glover (USA).sav`
88+
### Transfering Saves From An ED64
89+
If you are transferring a file from a different flashcart, such as the ED64, you must change the file extension to `sav`.
90+
For example, a save file called `Glover (USA).eep` should have its extension changed to `Glover (USA).sav` to work with N64FlashcartMenu.
9291

9392
You may also need to pad/trim the files to their original size:
9493
- For EEPROM 4Kbit games, remove the padding.
95-
- For others, use a tool such as Ninjiteu's N64 Save converter.
94+
- For others, use a tool such as [Ninjiteu's N64SaveConverter](https://github.com/Ninjiteu/N64SaveConverter).
9695

97-
**NOTE:** certain emulator saves or saves created for a different ROM version or region may be incompatible.
96+
**WARNING:** Saves created with certain emulators, or created for a different ROM version (as in revisions of the same game)
97+
or region (as in between NTSC and PAL versions of a same game) may be incompatible.

docs/01_menu_controls.md

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,27 @@
11
## Menu Controls
22

3-
### Fast scroll
4-
Use the C-Up and C-Down buttons
3+
### Additional Control Information
54

5+
#### Fast scroll
6+
Press either the `C-Up` or `C-Down` buttons to scroll by pages, rather than by elements.
67

7-
### DD ROMs
8+
#### N64FlashcartMenu settings
9+
Press the `START` button on the browser screen to open the Settings window. From here you can edit some of the N64FlashcartMenu settings,
10+
see information about either the console, the flashcart you are using or N64FlashcartMenu itself, and if your cart has Real-Time Clock (RTC) support,
11+
you can also change its date and time.
812

9-
#### Expansion Disks
10-
To load an expansion disk (e.g. F-Zero X) browse to the N64 ROM and load it (but not start it) and then browse to the DD expansion file and press the `R` button.
13+
#### Browser options
14+
Press the `R` button to open the Browser Options window. Here you can see a ROM's properties, delete it from your SD card or establish the default folder
15+
where N64FlashcartMenu's browser will start in future boots.
1116

12-
#### Disk swapping
13-
This feature is not currently available in the menu.
17+
#### Additional ROM information
18+
Press either the `L` or `Z` button on the ROM information screen to open an additional window that will show additional information about the currently
19+
selected ROM file, such as its endianess, regional variant, set clock rate, and much more.
20+
21+
### 64DD ROM
1422

23+
#### Expansion disks
24+
To load an expansion disk (such as F-Zero X), first browse to the N64 ROM and load it (**but not start it!**), then browse to the 64DD expansion file and press either the `L` or `Z` button.
25+
26+
#### Disk swapping
27+
This feature is not currently available in N64FlashcartMenu.

docs/07_menu_customization.md

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
# Menu customization
1+
## Menu Customization
22

3-
## Using a custom font
4-
Add a `font64` file to the root directory called "custom.font64"
5-
This can be build using `libdragon` tools.
3+
### Customizing the font
4+
Add a `font64` file to the root directory called "custom.font64". You can build a font64 file with the `libdragon` tools.

docs/99_developer_guide.md

Lines changed: 14 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,35 +2,34 @@
22

33
You can use a dev container in VSCode to ease development.
44

5-
### A quickstart video tutorial on how to set up your environment
5+
### A quickstart video tutorial on how to set up your environment
66
[![Devcontainer quickstart guide](http://img.youtube.com/vi/h05ufOsRgZU/0.jpg)](http://www.youtube.com/watch?v=h05ufOsRgZU "Devcontainer quickstart guide").
77

88

9-
### To deploy:
9+
### How to deploy
1010
#### SC64
11-
* Download the deployer [here](https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.20.0/sc64-deployer-windows-v2.20.0.zip)
11+
* Download the deployer [here](https://github.com/Polprzewodnikowy/SummerCart64/releases/download/v2.20.0/sc64-deployer-windows-v2.20.0.zip).
1212
* Extract and place `sc64deployer.exe` in the `tools/sc64` directory.
1313

14-
Make sure that your firmware is compatible (currently v2.20.0+)
14+
Make sure that your firmware is compatible (currently v2.20.0+).
1515
See: [here](https://github.com/Polprzewodnikowy/SummerCart64/blob/v2.20.0/docs/00_quick_startup_guide.md#firmware-backupupdate)
1616

1717
##### From the devcontainer
18-
It is not currently possible to directly communicate with USB devices.
19-
BUT, as a workaround you can use a proxy TCP/IP connection
20-
Set up a proxy: open a terminal window, `cd ./tools/sc64` and then `./sc64deployer.exe server`
18+
It is not currently possible to directly communicate with USB devices. BUT, you can use a proxy TCP/IP connection as a workaround.
19+
To set up a proxy, open a terminal window, `cd ./tools/sc64` and then `./sc64deployer.exe server`.
2120

22-
Then in the dev container, use `make run` or `make run-debug`
21+
Then, in the dev container, use `make run` or `make run-debug`.
2322

2423

2524
##### From your host (Windows) OS
2625

27-
* Run `./localdeploy.bat` from the terminal
26+
* Run `./localdeploy.bat` from the terminal.
2827

29-
Toggle the N64 power switch to load the ROM.
28+
Toggle the N64 POWER switch to load the ROM.
3029

31-
`ms-vscode.makefile-tools` will help (installed automatically in dev container).
32-
NOTE: it does not yet work with `F5`: see [this blog post](https://devblogs.microsoft.com/cppblog/now-announcing-makefile-support-in-visual-studio-code/)
33-
WORKAROUND: in the dev container terminal, use make directly, i.e.: `make`
30+
`ms-vscode.makefile-tools` will help (installed automatically in dev container).
31+
NOTE: it does not yet work with `F5`: see [this blog post](https://devblogs.microsoft.com/cppblog/now-announcing-makefile-support-in-visual-studio-code/).
32+
WORKAROUND: in the dev container terminal, use make directly, i.e.: `make`.
3433
The ROM can be found in the `output` directory.
3534

3635
NOTE: a "release" version of the SC64 menu is called `sc64menu.n64` and can be created for when you want to add it directly to the SDCard. This is generated by running `make all` or running `make sc64`.
@@ -53,11 +52,10 @@ This repo currently uses the `preview` branch as a submodule at a specific commi
5352
* To ensure your local instance is building against it, use `cd ./libdragon && make clobber -j && make libdragon tools -j && make install tools-install -j && cd ..`
5453

5554
## Generate documentation
56-
Run `doxygen` from the dev container terminal.
57-
Make sure you fix the warnings before creating a PR!
55+
Run `doxygen` from the dev container terminal. Make sure you fix the warnings before creating a PR!
5856
Generated documentation is located in the `output/docs` folder and auto-published to the `gh-pages` branch when merged with `main`.
5957

60-
Once merged, they can be viewed [here](https://polprzewodnikowy.github.io/N64FlashcartMenu/)
58+
Once merged, they can be viewed [here](https://polprzewodnikowy.github.io/N64FlashcartMenu/).
6159

6260
### Test generated docs in the dev-container
6361
Testing the documentation locally allows you to preview changes and ensure everything renders correctly before submitting your changes.

0 commit comments

Comments
 (0)