Comments (8)
I offer to prefix all hexadecimal numbers with 0x
and following with uppercase letters, like: 0xFE9F
. This will remove the mental load to figure out which base a number in. Currently h
suffix is used, like 10h
. The assembly style $
prefix is doesn't tell much about the base for those never touch the assembly. Even worse some numbers have no prefix or suffix, but just the way it's written shows its base like: FF03
.
Same way we can also prefix binaries with 0b
, as in 0b0000'1111
or 0b11
.
from pandocs.
Wasn't it decided elsewhere to use RGBDS notation? ($c0de
, %0010_1010
)
from pandocs.
The decision was to use $
for hex and just explicitly mentioning that numbers are binary when they are: https://github.com/gbdev/pandocs/wiki/Document-Style#units-and-prefixes
Something like 0b11
is extremely confusing for someone who hasn't seen the notation before (as it can be rightfully mistaken for a hexadecimal number); that notation should never be used in any form of documentation that doesn't target a specific programming language (or family of languages) that already uses that notation.
from pandocs.
Adapting notation from a programming language doesn't necessarily a bad thing IMO. And current notation already adapted from assembly.
The PanDocs needs much more bold and concrete notation, statements, wording and details on overall document. Current state is far from useful to help inspired emulator developers. Lots of the time new emulators ended up implementing others emulator, which effectively being a port of another emulator. Because the ambiguities on the docs here and there make creative emulators impossible. PanDocs can be good candidate to do original jobs because lots of experiences people are interested in it someway. Creating road map can be useful.
0b11
might be confusing, but 0b0000'0011
would be sufficiently understandable.
from pandocs.
Pan Docs does not try to be a resource for emulator developers, but for homebrew developers. gb-ctr is much better suited to emu dev.
from pandocs.
Unfortunately PPU part is incomplete, which is one of the core part of emulators. I can appreciate how difficult constructing a factually correct sentence on a technical matter though. Different docs are has different depth on subsystems. The gb-ctr does good job on CPU instructions and timing.
I would like to see some kind of merger with the PanDocs, some kind of pipeline that offer complete documentation that render pdf from every tag. Such a merger and crediting authors in proper way, will be helpful for community and history preservation.
from pandocs.
Adapting notation from a programming language doesn't necessarily a bad thing IMO. And current notation already adapted from assembly.
I agree. But before anything, we need to put workflows and standards in place, since the document is still very inconsistent. We already had the discussion for hex strings, but you're welcome to open another issue to change the decision.
From what I've seen, binary strings are (or can be made) very clear from the context anyway, so I don't we think we need another prefix.
The PanDocs needs much more bold and concrete notation, statements, wording and details on overall document.
This is true and every PR directed at improving this is welcome. Stating these guidelines will be very useful too.
PanDocs can be good candidate to do original jobs because lots of experiences people are interested in it someway. Creating road map can be useful.
I agree and this kind of stuff should be discussed (roadmap is a good idea), but this is not currently our goal and there's a lot work just to standardise, correct and format the current information, let alone add o restructure stuff (just take a look at the issues). gb-ctr
is much more suited at the moment.
from pandocs.
What's the status on this? 1. and 4. are covered by #163, 2. has been fixed, and 3. is now part of the style guide, so it's "just" general cleanup now.
from pandocs.
Related Issues (20)
- Make raster images selectively sharp HOT 2
- Undocumented SGB Hardware quirk: Command packet bytes are buffered
- a11y: add alt text and check if the existing ones are descriptive enough
- Mention MBC30 in MBC3 documentation HOT 1
- Allow building out-of-tree HOT 2
- Make "single" page self-referential
- Markup is not allowed in admonitions titles HOT 1
- Contributing: document how to export SVGs
- Open external links in a new tab
- Build reproducibility: pull fonts from npm HOT 3
- Make single-page and PDF version more visible HOT 4
- Hardware register default value doesn't make sense on DMG for CGB-only registers HOT 4
- Serial transfer is re-described in the interrupts page
- Make bits-description table separations more visible HOT 5
- Vram map - suggestion
- "Timer Obscure Behavior" needs an overhaul HOT 1
- Average loading time is > 8 seconds HOT 2
- SGB command packet transfers are described using wrong bits of JOYP HOT 1
- 0xFF0F - Interrupt flag, not mentioned in memory layout HOT 3
- Registers "default return values" no longer mentioned HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from pandocs.