It is currently Tue Nov 20, 2018 4:34 pm

All times are UTC - 7 hours





Post new topic Reply to topic  [ 11 posts ] 
Author Message
PostPosted: Fri Oct 19, 2018 2:24 pm 
Offline

Joined: Tue Jun 28, 2011 2:39 pm
Posts: 192
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.


Top
 Profile  
 
PostPosted: Fri Oct 19, 2018 2:37 pm 
Offline

Joined: Sun Apr 13, 2008 11:12 am
Posts: 7723
Location: Seattle
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.
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.


Top
 Profile  
 
PostPosted: Fri Oct 19, 2018 2:38 pm 
Offline
User avatar

Joined: Sun Jan 22, 2012 12:03 pm
Posts: 6961
Location: Canada
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?


Top
 Profile  
 
PostPosted: Sat Oct 20, 2018 4:36 am 
Offline

Joined: Tue Jun 28, 2011 2:39 pm
Posts: 192
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).
lidnariq wrote:
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.

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.


I'm talking about actual board schematic, such as this one (random google search for PCB schematic):
Image


Top
 Profile  
 
PostPosted: Sat Oct 20, 2018 5:30 am 
Offline
User avatar

Joined: Sun Jan 22, 2012 12:03 pm
Posts: 6961
Location: Canada
darkhog wrote:
Except these differences actually make some code non-trivial to translate, e.g. ca65 .bank syntax. Not to mention NESASM general weirdness.

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?


Top
 Profile  
 
PostPosted: Sat Oct 20, 2018 12:58 pm 
Offline

Joined: Sun Apr 13, 2008 11:12 am
Posts: 7723
Location: Seattle
darkhog wrote:
I'm talking about actual board schematic, such as this one (random google search for PCB schematic):
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.


Top
 Profile  
 
PostPosted: Sat Oct 20, 2018 1:44 pm 
Offline
User avatar

Joined: Fri May 08, 2015 7:17 pm
Posts: 2334
Location: DIGDUG
The wiki could use mapper specific example code* and/or templates.

*Like proper operation of MMC3 scanline counter.

_________________
nesdoug.com -- blog/tutorial on programming for the NES


Top
 Profile  
 
PostPosted: Sat Oct 20, 2018 7:19 pm 
Offline
User avatar

Joined: Tue Jun 24, 2008 8:38 pm
Posts: 2056
Location: Fukuoka, Japan
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.


Top
 Profile  
 
PostPosted: Sat Oct 20, 2018 7:34 pm 
Offline
User avatar

Joined: Sun Jan 22, 2012 12:03 pm
Posts: 6961
Location: Canada
Banshaku wrote:
- do we stay assembler agnostic?

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:
- does it has to be a complete compile-able sample or just a snippet?

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.

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.)


Top
 Profile  
 
PostPosted: Sat Oct 20, 2018 8:10 pm 
Offline
User avatar

Joined: Sat Feb 12, 2005 9:43 pm
Posts: 10977
Location: Rio de Janeiro - Brazil
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.


Top
 Profile  
 
PostPosted: Wed Oct 31, 2018 2:55 am 
Offline
User avatar

Joined: Fri Nov 12, 2004 2:49 pm
Posts: 7580
Location: Chexbres, VD, Switzerland
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.

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.

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.

Quote:
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?

My vote is for assembler agnostic and just a snippet.


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 11 posts ] 

All times are UTC - 7 hours


Who is online

Users browsing this forum: No registered users and 0 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Powered by phpBB® Forum Software © phpBB Group