Suggestions to improve wiki's content
Moderator: Moderators
Suggestions to improve wiki's content
1. When you need to put schematic of a board, put actual schematic of the board (as an image), instead of terrible ascii art as it is case with e.g. UNROM-512 schematic on the wiki.
2. When putting code samples, translate it to most used assemblers (in this moment AFAIK that would be ca65, NESASM and ASM6) as to not confuse new developers with assembler differences so they wouldn't have to translate it themselves and instead they could easily see it in a syntax they're most comfortable with (unless it's some exotic assembler in which case the dev probably knows what he's doing anyways).
I feel like if these two suggestions would be followed up on and put into practice across the wiki, it'd be much better source of information for developers new to NES.
2. When putting code samples, translate it to most used assemblers (in this moment AFAIK that would be ca65, NESASM and ASM6) as to not confuse new developers with assembler differences so they wouldn't have to translate it themselves and instead they could easily see it in a syntax they're most comfortable with (unless it's some exotic assembler in which case the dev probably knows what he's doing anyways).
I feel like if these two suggestions would be followed up on and put into practice across the wiki, it'd be much better source of information for developers new to NES.
Re: Suggestions to improve wiki's content
Please say more. I don't personally understand how the ASCII art schematic is obfuscatory, or how the same information would be clearer if drawn as a picture.darkhog wrote:1. When you need to put schematic of a board, put actual schematic of the board (as an image), instead of terrible ascii art as it is case with e.g. UNROM-512 schematic on the wiki.
- rainwarrior
- Posts: 8732
- Joined: Sun Jan 22, 2012 12:03 pm
- Location: Canada
- Contact:
Re: Suggestions to improve wiki's content
1. I think there's an advantage of ascii diagrams in that they're much easier to edit, and less data to load. That said, I don't really care for one way or the other as long as the information is clearly organized, but all I'd say is that I doubt anyone will volunteer to change all the diagrams on the wiki to match your preference. The reason we have those diagrams at all is because someone was interested enough to make them in the first place.
2. I actually would not like to see the wiki cluttered with triplicates of every code sample. As long as it states which assembler to use, I think one version is fine. In most cases for small examples the syntax differences should be trivial/inconsequential to the example (sometimes none needs to be specified). Is there a specific code example that you thought was hard to understand in your not-favourite-assembler syntax?
2. I actually would not like to see the wiki cluttered with triplicates of every code sample. As long as it states which assembler to use, I think one version is fine. In most cases for small examples the syntax differences should be trivial/inconsequential to the example (sometimes none needs to be specified). Is there a specific code example that you thought was hard to understand in your not-favourite-assembler syntax?
Re: Suggestions to improve wiki's content
Except these differences actually make some code non-trivial to translate, e.g. ca65 .bank syntax. Not to mention NESASM general weirdness.
Other code could be hidden in some openable box, like [spoiler] bbcode tag that is present on certain forums (not this one though).
Other code could be hidden in some openable box, like [spoiler] bbcode tag that is present on certain forums (not this one though).
I'm talking about actual board schematic, such as this one (random google search for PCB schematic):lidnariq wrote:Please say more. I don't personally understand how the ASCII art schematic is obfuscatory, or how the same information would be clearer if drawn as a picture.darkhog wrote:1. When you need to put schematic of a board, put actual schematic of the board (as an image), instead of terrible ascii art as it is case with e.g. UNROM-512 schematic on the wiki.
- rainwarrior
- Posts: 8732
- Joined: Sun Jan 22, 2012 12:03 pm
- Location: Canada
- Contact:
Re: Suggestions to improve wiki's content
Could you point to a code example on the wiki that uses .bank, or otherwise a code example on the wiki that you think demonstrates one of these irreconcilable differences, or is otherwise confusing to you?darkhog wrote:Except these differences actually make some code non-trivial to translate, e.g. ca65 .bank syntax. Not to mention NESASM general weirdness.
Re: Suggestions to improve wiki's content
I know what a schematic looks like. What I don't understand is how the same information drawn with lines or with ASCII art producing lines makes the information easier or harder to understand.darkhog wrote:I'm talking about actual board schematic, such as this one (random google search for PCB schematic):
Re: Suggestions to improve wiki's content
The wiki could use mapper specific example code* and/or templates.
*Like proper operation of MMC3 scanline counter.
*Like proper operation of MMC3 scanline counter.
nesdoug.com -- blog/tutorial on programming for the NES
Re: Suggestions to improve wiki's content
The programmer's guide section was for that purpose when I created it but I was off the radar for a while so those examples never materialized ^^;;
But I agree, we need more programmer's example for basic usage so I wouldn't have had to create a lengthy thread about basic usage of mmc3 if there was already such sample, I guess.
I could try to make some of them but the main issue would be:
- do we stay assembler agnostic?
- does it has to be a complete compile-able sample or just a snippet?
Depending of the scope, it does make a difference on how long it takes to make.
But I agree, we need more programmer's example for basic usage so I wouldn't have had to create a lengthy thread about basic usage of mmc3 if there was already such sample, I guess.
I could try to make some of them but the main issue would be:
- do we stay assembler agnostic?
- does it has to be a complete compile-able sample or just a snippet?
Depending of the scope, it does make a difference on how long it takes to make.
- rainwarrior
- Posts: 8732
- Joined: Sun Jan 22, 2012 12:03 pm
- Location: Canada
- Contact:
Re: Suggestions to improve wiki's content
I'd just suggest to use whichever assembler is most convenient, and maybe mention what it is. The bulk of any assembly code is mostly "agnostic" anyway, under normal circumstances, especially when we're talking about small didactic examples.Banshaku wrote:- do we stay assembler agnostic?
If you want to link a buildable project there's probably lots of other stuff you want to include. Attach it to a thread and link the thread from the wiki.Banshaku wrote:- does it has to be a complete compile-able sample or just a snippet?
In my opinion, the primary point of a code example on the wiki should be to show how to do something. Making something you can copy-paste should be secondary to that. (Though, this is part of why I don't think it really matters which assembler is used. Reading and understanding code is hampered by these differences a lot less than copy-paste behaviour is.)
Re: Suggestions to improve wiki's content
As long as you avoid assembler-specific directives and special labels (local, anonymous, etc.), the code should be easy to follow by anyone. If you absolutely have to show more controversial tasks, such as defining variables, try to do it in a conventional way that's easy to understand (e.g. MyVar = $4F), even if it's not the way you'd do it in your own projects.
NESASM's discrepancies such as []s instead of ()s for indirection, HIGH() and LOW() instead of < and >, and so on, should be noted somewhere, but we can't forget that NESASM is the exception when it comes to 6502 syntax.
NESASM's discrepancies such as []s instead of ()s for indirection, HIGH() and LOW() instead of < and >, and so on, should be noted somewhere, but we can't forget that NESASM is the exception when it comes to 6502 syntax.
Re: Suggestions to improve wiki's content
Sorry but your idea 2. is goddamn awful. We don't want every code sample to be there (and having to be maintained) thrice, nor do we want people to copy/paste code from the wiki into their code and ever expecting to work. This is just samples, they're supposed to show a general idea that can be reused in people's code, not to be copy/pasted into people's code.darkhog wrote:1. When you need to put schematic of a board, put actual schematic of the board (as an image), instead of terrible ascii art as it is case with e.g. UNROM-512 schematic on the wiki.
2. When putting code samples, translate it to most used assemblers (in this moment AFAIK that would be ca65, NESASM and ASM6) as to not confuse new developers with assembler differences so they wouldn't have to translate it themselves and instead they could easily see it in a syntax they're most comfortable with (unless it's some exotic assembler in which case the dev probably knows what he's doing anyways).
I feel like if these two suggestions would be followed up on and put into practice across the wiki, it'd be much better source of information for developers new to NES.
As for idea 1, I agree actual schematic would look better than ASCII art, but how could we edit them ? Sure we could use SVG or something similar, but it'd be harder to integrate and edit.
My vote is for assembler agnostic and just a snippet.I could try to make some of them but the main issue would be:
- do we stay assembler agnostic?
- does it has to be a complete compile-able sample or just a snippet?