Dan Docs

[avivace]

Dan Docs documents more obscure Game Boy hardware. It is rendered from here https://github.com/shonumi/shonumi.github.io/blob/master/dandocs.html, which in turns comes from GBE docs : https://github.com/shonumi/gbe-plus/blob/master/src/docs/technical/dandocs.html, manually converted to HTML from the TXT files in the same folder, like this one: https://github.com/shonumi/gbe-plus/blob/master/src/docs/technical/Mobile_Adapter_GB.txt

We could script something to automatically render those TXT as MD and then have our new Pan Docs website render an updated (an in sync with Shonumi/GBE docs) version of Dan Docs.

Dan Docs is public domain, but the author, @Shonumi mentioned:

There may be an issue with some disassembly from Zok Zok Heroes (which I've been meaning to address).

[asiekierka]

I'm not sure that's the best approach - the Dan Docs seem to rely to a large extent on hand-written ASCII tables, as well as having some sections which overlap with existing sections in the Pan Docs (GBC Infrared). I would also refrain from the disassemblies and providing fragments of data (such as barcode IDs) used by games - focusing solely on the programming aspect of each hardware.

[shonumi]

I should have commented on this a long time ago, I suppose. Apologies for the lateness. No one's showed any interest in merging Pan Docs and Dan Docs, so I'd forgotten all about this open issue altogether.

Dan Docs fortunately no longer contains the Zok Zok Heroes disassembly. It's been replaced with C-like psuedo code. I have no real opinion whether said psuedo code fits anywhere into Pan Docs or not, but it should be mentioned that the copyright concerns there have hopefully be taken care of now. That was a big worry of mine.

The IR section contains some useful programming information not currently mentioned in Pan Docs (obscure behavior with the RP register, more details on the signal fading). Rather than copying a dedicated IR section over from Dan Docs, the existing Pan Docs section could be updated with missing information in this case.

On that note, copy+pasting all of Dan Docs is probably not ideal to integrate it with Pan Docs. Each item/accessory would probably have to be rewritten to better conform with the tone and scope of the rest of Pan Docs, rewording and reworking it so everything feels and reads cohesively. It's a large task, but unless that approach is done, it's just two separate documents stuck together. Their primary goals are different after all (Pan Docs targets homebrew development, Dan Docs aims to incorporate as much data as possible). Despite the similar naming scheme, Dan Docs is modeled after GBATEK as opposed to Pan Docs.

This is one big reason why Dan Docs is Public Domain. I'm very supportive of any changes people want or need to make. The info belongs to everyone, so whoever wants to merge it with Pan Docs can pick and choose freely, adding, deleting, or totally changing whatever is necessary.

[ISSOtm]

I should have commented on this a long time ago, I suppose. Apologies for the lateness. No one's showed any interest in merging Pan Docs and Dan Docs, so I'd forgotten all about this open issue altogether.

No worries, many issues here could be solved fairly quickly, but sometimes it's not easy to keep track of everything we are involved in... :P

The IR section contains some useful programming information not currently mentioned in Pan Docs (obscure behavior with the RP register, more details on the signal fading). Rather than copying a dedicated IR section over from Dan Docs, the existing Pan Docs section could be updated with missing information in this case.

Being taken care of in #327 thanks to @asiekierka :)

On that note, copy+pasting all of Dan Docs is probably not ideal to integrate it with Pan Docs. [...] Their primary goals are different after all (Pan Docs targets homebrew development, Dan Docs aims to incorporate as much data as possible). Despite the similar naming scheme, Dan Docs is modeled after GBATEK as opposed to Pan Docs.

Agree on keeping the split, if only for scope reasons. (This is also why I'm less sure about #328, the GB Camera, and GameShark pages in Pan Docs.)

This is one big reason why Dan Docs is Public Domain. I'm very supportive of any changes people want or need to make. The info belongs to everyone, so whoever wants to merge it with Pan Docs can pick and choose freely, adding, deleting, or totally changing whatever is necessary.

Note that Pan Docs is public domain as well, so we agree and there's no conflict there :)

[asiekierka]

I think, generally, accessories which are usable to programmers and compatible with the GB/GBC should be documented in the Pan Docs. However, things which are not relevant for people developing for the platform (Game Genie/Game Shark cheats, or Dan Docs's notes on specific game compatibility/behaviour) should not be in the Pan Docs.

The question is - where to draw the line? There's some notable edge cases:

• The GB/GBC has had some peripherals intended for a wider audience (like the 4-Player Adapter), but also truly obscure peripherals like the sewing machine thing. What about these?
• There are both accessories (keyboard adapter) and mappers (TPP1) being developed by the homebrew community. Where should these be documented?

It would be good to consider the HuC1/EMS/Wisdom Tree mapper documentations in the same light, probably.

[ISSOtm]

By this logic, the GB Camera should be documented as well, since it's technically possible to run your own code in RAM and cartswap to a Camera cartridge, then interface with it. I think this does not warrant a spot in the Pan Docs.

I'd draw the line at a (subjective) ease of accessibility for homebrew, and this includes emulation. (Since emulators may offer Hu-C1 support, for example, it may be worth documenting. Maybe. See next paragraph.)

However, Pan Docs is also an important resource to emulator developers, and so (I believe that) what is documented in the Pan Docs has a higher chance of being more widely implemented. However, documenting too much would likely overwhelm... I dunno. Maybe I'm overthinking this.

[asiekierka]

If the target is emulators, all accessories made commercially available should be documented. If the target is on-device homebrew, then the GB Camera should probably be skipped. (But in both cases, what about the mappers? We have, for example, Daid's notes on the EZ-Flash Junior's memory-mapped interface; this would certainly be of use to some types of homebrew and emulator development.)

Remember that the end goal of the Pan Docs is to be a complete reference; the more asterisks you put on "complete", the less complete it becomes.

[ISSOtm]

The target is on-device homebrew, but I know that Pan Docs is still a recommended reference for emulator developers. We don't document all the fine details, though, gb-ctr does. The same applies here, imo.

[asiekierka]

In that case, I would stick to "what can a homebrew developer actually target on a real device", which would exclude the GameBoy Camera, but not exclude rare peripherals which were made commercially available (some of which aren't that expensive to acquire at all, especially compared to how high the prices for modding and acquiring a GBC can get).

I'm not sure on mappers, though. There's two issues:

• Nothing is technically stopping you from making a new, say, Wisdom Tree-mapper cartridge - but at that point, you might as well make an entirely custom mapper. Is it worth to document MBCs beyond the quadfecta of MBC1/MBC2/MBC3/MBC5, in this context? What about mappers made specifically for homebrew, like the TPP1?
• There's the newer flashcarts' built-in memory mapped interfaces, which homebrew developers could absolutely incorporate if detected. For example, the EZ-Flash Junior, IIRC, contains 512KB of SRAM rather than 128KB.

[ISSOtm]

Imo, documenting for example MBC6 is worth, since it offers a different banking scheme, and thus significant possibilities.

I don't think Pan Docs should aim to document moving targets, which would exclude flashcart interfaces (since those may be patched) and mappers like the TPP1. (People should be made aware of them another way.) Also custom mappers without a spec, since those would just be defined by a single implementation.

[pinobatch]

Nothing is technically stopping you from making a new, say, Wisdom Tree-mapper cartridge - but at that point, you might as well make an entirely custom mapper.

What stops someone from making a new custom mapper cartridge is that the popular debugging emulators are proprietary: BGB and Emulicious. Unlike with a free emulator, a user with a specification document for a custom mapper cannot add support for that mapper to a proprietary emulator for the purpose of single-stepping through a 1-second-old build of a program before writing it to the cartridge. This encourages people to shoehorn their multicart projects into Wisdom Tree or EMS rather than designing something original.

[asiekierka]

I don't think that's relevant - someone willing to go as far as to patch an emulator to support their mapper (and, presumably, write and design the hardware logic too) can probably deal with something like SameBoy's textual debugger interface.

In general, the question is of theoretical, not practical possibility, to me.