It was only 1 page, which is more or less my point. It's not the DATA statements I'm worried about, but the mysterious setup and complicated read loop that the X16 will need in order to achieve an equivalent example. For example, here's the setup needed for the VIC20:
It's 2 variables and a single POKE. Not bad at all. Here's the equivalent for the X16's YM2151 chip:
Quote
5 YA=$9F40 : YD=$9F41 : V=0
10 REM: MARIMBA PATCH FOR YM VOICE 0 (SET V=0..7 FOR OTHER VOICES)
20 DATA $DC,$00,$1B,$67,$61,$31,$21,$17,$1F,$0A,$DF,$5F,$DE
30 DATA $DE,$0E,$10,$09,$07,$00,$05,$07,$04,$FF,$A0,$16,$17
40 READ D
50 POKE YA,$20+V : POKE YD,D
60 FOR A=$38 TO $F8 STEP 8
70 READ D : POKE YA,A+V : POKE YD,D
80 NEXT A
It's a full on READ loop using values on lines 20 and 30 that are far from easily explained. A manual that explains those values to advanced users is fine, but the low end of my target demographic is 6-8 year olds. Any explanation of lines 20 and 30 simply isn't going to be acceptable (although you're welcome to post your best effort).
The READ loop in the VIC20 manual is also fairly simple:
It reads the note, checks the end condition, reads the duration, plays the note, and waits the duration. It's very simple to document. Here's the X16's version:
Quote
90 READ P
100 IF P < 0 THEN 300
110 READ D
120 POKE YA,$29
130 POKE YD,P
140 POKE YA,$08
150 POKE YD,$00+1
160 POKE YD,$78+1
170 FOR N=1 TO D : NEXT N
180 POKE YD,$00+1
190 FOR N=1 TO 20 : NEXT N
200 GOTO 90
There's too many magic numbers in there to understand what is being set. When you put this all together, you get one of those type-in programs that nobody understands, but just type because you trust it will work:
For a beginner-targeted user manual, annotations need to be considered. I'll argue that properly documenting the above code would require more bubbles than would fit on the page. The code, itself, wouldn't fit on a single page the way the VIC20 example does.
Meanwhile, having a single statement that loads the instrument and a single statement to play a note would turn the above code into more or less the exact same thing as the VIC20 example. No unexplainable magic numbers would have to be typed.
