gbdev / rgbds-www Goto Github PK
View Code? Open in Web Editor NEWRGBDS website, hosting documentation and install instructions. Built with Docusaurus, content from RGBDS man pages.
Home Page: https://rgbds.gbdev.io
License: Other
RGBDS website, hosting documentation and install instructions. Built with Docusaurus, content from RGBDS man pages.
Home Page: https://rgbds.gbdev.io
License: Other
A README file, quickly explaining the steps needed to build and deploy the website, how the documentation is included (how different versions are handled, etc) is very much needed.
How could we better ask for help in maintaining (and developing new features) for RGBDS?
Some ideas:
Line 91 in 497e92b
Should it be #cc8
, #ccccc8
, or what?
As we're now publishing the RGBDS container package, the docker option should be mentioned in the Install page
We modify a bit the mandocs.css
distributed upstream with the mandoc
package:
manual-text
classes, so they don't get applied to all the websiteWe should script this so we can pull upstream a recreate our version without a human intervention
Hardware.inc and (depending on maintenance commitments) RGBDS structs should be linked or referenced by the docs, possibly directly in the man docs
According to the documentation for the GBZ80 instructions that is currently online:
RRA
fills the 8th bit with the value of the carry flag (aka: C -> [7 -> 0] -> C
)RRCA
fills the bit with a zero (aka: 0 -> [7 -> 0] -> C
)However, according to what I am seeing when I actually assemble some code, the opposite is true:
RRA
fills the 8th bit with a zero (aka: 0 -> [7 -> 0] -> C
)RRCA
fills it with the carry flag (aka: C -> [7 -> 0] -> C
)I am not sure if I am missing something here, or whatever, but I thought I would bring it to your attention.
It would be nice to support an alternative dark mode.
The FAQ claims you need to "make sure there is no whitespace (spaces or tabs) before the macro’s name", but foo: MACRO
and the new MACRO foo
can now both have whitespace before them. The remaining gotcha with whitespace is to try and invoke a macro foo
without any leading whitespace.
Going to #breadcrumbs
works, but that seems weird.
I'm thinking the front page would be appropriate. We would surely want to keep it simple, so I'm thinking of a video of assembling the following ROM and running it in an emulator?
SECTION "Header", ROM0[$100]
EntryPoint:
jp Main
ds $150 - @, 0 ; Reserve some space for RGBFIX to fill in the header.
SECTION "Main", ROM0
Main:
; Wait for VBlank.
.waitVBlank
ldh a, [rLY]
cp 144
jr nz, .waitVBlank
; Move the Nintendo logo left a little.
ldh a, [rSCX]
inc a
ldh [rSCX], a
; And keep going!
jr Main
Originally posted by @ISSOtm in gbdev/rgbobj#9 (comment)
This ticket tracks the progress of migration of the RGBDS project website to a React based stack (Docusaurus).
Currently, the work is being done in this repository, which is being built at https://gbdev.io/rgbds-www2/. Anybody is invited to give feedback or join the development there.
Why:
The plan is to
bash
, as DaKnig mentioned in #1002g++
for rgbgfx
CMake build type defaults to None. Need to pass -DCMAKE_BUILD_TYPE=Release on the command-line.
https://github.com/gbdev/rgbds-www/blob/master/_installation/source.md (and RGBDS readme)
We could provide alternative styling, for example modifying the font size, providing a dark mode, and disabling text justification (I was told dyslexic people have trouble with it).
Additionally, it should be possible to use prefers-color-scheme
to set the default color scheme, for example.
There are two problems:
Problem 1 could be solved using some JS and browser storage, as I've seen some sites do.
For Problem 2, I'm thinking we could add some button at the bottom of the page, that'd open a drop-down/pop-up of toggles?
What about adding a "Try" or "Playground" link in the main navbar? (or in the main action buttons in the home page)?
Side question: should we fork rgbds-live?
Examples:
LDH [C], A
LD [HL], r8
The documentation includes symbols that aren't explained. For example, it's assumed that the reader will know what square brackets indicate. This knowledge should be readily available. I suggest adding a couple thoroughly-explained examples below the legend which cover each of the different syntax for the documentation. You could call it "Comprehending this document" or something.
Some tables in the RGBASM language description are too large, and cause overflow that breaks the page layout.
A content fix isn't the way to go, as I would prefer not to touch the previous versions' pages.
Apparently, MSYS2, like Cygwin, basically runs Windows executables from its own prompt; thus, RGBDS can be installed on it by simply placing a copy of rgb*.exe
in its bin/
folder.
Mention this in the install instructions, and perhaps add a caveat that Cygwin is fairly slow.
E.g. when we'll be on Debian, mention Debian and Arch/AUR
On the main page (https://rgbds.gbdev.io/), near the bottom, under "More", there's a link with the text "Game Boy Development resources" leading to https://gbdev.io/list.html#introduction, which is a broken link. Maybe it should link to https://eldred.fr/gb-asm-tutorial/resources.html instead?
I was just looking at the OP code reference and the wordings are, let's say, quite interesting. Someone changed the documentation to include meme references (see screenshot below). I searched for some strings in the repo, but couldn't find any matches, so I'm guessing some funny guy changed the HTML files on the server. It's very funny and all, but it's quite distracting. Can it be changed back?
This misrepresents hex literals like "0xFF" or "0x143".
(Using a custom font also causes a "flash of unstyled text" as the @font-face
loads. I'd recommend listing just standard fonts that come with Windows, macOS, and typical Linux.)
See: #60
To fix this, the anchors should be moved up by the navbar's height. The question then becomes how to do this... JS could be used, but not everyone enables JS; we can't use a custom Jekyll plugin because GitHub Pages prevents it; and I didn't find such a plugin among the whitelisted ones.
An alternative would be making the main content scroll within itself, instead of the whole <body>
scrolling; I'm however not sure how to achieve that.
The main landing page on https://rgbds.gbdev.io/ does not have links to:
the website mentions the page rgbasm.5 multiple times, but links to a non existing page rgbds.5/rgbasm.5 which 404s...
People often leave previews in Discord links, and https://rgbds.gbdev.io appears as its logo image, a low-res square RGB icon.
Looking at GitHub's "social media preview" feature, this HTML header content would suffice for Discord and Twitter at least:
<meta name="twitter:image:src" content="https://rgbds.gbdev.io/preview.png" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:site" content="@github" />
<meta name="twitter:title" content="RGBDS: ..." />
<meta name="twitter:description" content="RGBDS: ..." />
<meta property="og:image" content="https://rgbds.gbdev.io/preview.png" />
<meta property="og:type" content="object" />
<meta property="og:site_name" content="GitHub" />
<meta property="og:url" content="https://rgbds.gbdev.io" />
<meta property="og:image:alt" content="RGBDS: ..." />
<meta property="og:title" content="RGBDS: ..." />
<meta property="og:description" content="RGBDS: ..." />
An example of its current appearance:
default.scss styles body
with text-align: justify;
. Browsers aren't good at text justification, and this causes some words to be separated by too much whitespace. Inline style tags interact badly with justification too, causing their contents to be grouped separately. I find the pages easier to read, especially the man docs, with the default left justification.
mandoc
is able to produce PDF exports, so we should be able to serve those as well. They've been requested a couple times.
It has been reported (at least by @ZaidMade and @AntonioND) that the stylesheet needs to be reworked. (The former forked the site, though it's broken due to #15.)
Suggested fixes:
Roboto
in frontThis would be useful to check 404s on the site, and possibly more.
Since the upstream source of the actual content is from the mandocs in the main repository, "edit page" / contribute links should not point to their rendered versions here. We should rewrite them to point to the real sources (or just don't show those).
This should also made clear in the Contributing guidelines.
We are missing a CONTRIBUTING.md file for this repository
The current installation instructions are potentially confusing, more so for the users who need the help most (typically Windows ones).
We have a lot of ways to install RGBDS; in no particular order:
brew
, or (most complicated) Cygwinmake
or cmake
cmake
versionsPATH
for Windows
cmd
or Powershellrgbenv
(which has its own build instructions)master
development branch...
I think we should prioritize using the releases published on GitHub (with a separate page for Windows users explaining how to add the new .exe files to their PATH
).
Secondly, mention the packaged options for macOS and Arch Linux.
Thirdly, a separate page on how to build from source. This would have sections on how to install the prerequisites (with apt
, pacman
, brew
, Cygwin, etc), get the source (download the .zip or git clone
), build (make
or cmake
), and install (make install
or adding to PATH
).
I plan to use a feature added in gbdev/rgbds#1159 in a Game Boy project, and I want to know what to tell contributors who use Windows to install until RGBDS 0.6.2 comes out. I'm having trouble finding on the website how to obtain and install Windows executables of RGBDS master
built by a GitHub Actions job.
Windows
then "Plain" Windows
, follow "go here". Broken. This link leads to a nonexistent anchor using-rgbds-master
.Windows
then "Plain" Windows
, follow "use master
", then follow "use our CI". Broken. This link leads back to install
under a nonexistent anchor using-our-ci
.The correct answer appears to be this: In https://rgbds.gbdev.io/install, follow "using a development version", then scroll down to "Using our CI" and follow "made available on GitHub". Then under "workflow run results", follow the name of the most recent PR with a green check next to master
, scroll down to "Artifacts", and then download rgbds-canary-win64
.
Aside: The "go here" phrasing for the call to action is deprecated by a W3C article, which claims that noun phrases make the clearest CTA. According to "The problem with 'click here' and 'learn more' links" by Cynthia Marinakos, it slows the reader and creates a feeling of risk. Answers to questions on UX Stack Exchange and Webmasters Stack Exchange explain what an author can do about "here" in links.
Currently, the site assumes that baseUrl
is empty, i.e. that the site is at the domain's root. This breaks forks that use different URLs (example).
Note that Jekyll has the relative_url
filter for this.
Each of the pages shows a tooltip for links on mouseover. This is likely useful, but completely unexplained. Some sort of link tooltip legend would be nice.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.