Language Documentation
loretoparisi opened this issue · 16 comments
Please add the WWWBasic language documentation.
I think it might be based on IBM PC-BASIC but a reference would definitely be helpful.
@RandomGuyDTB thanks, I was wondering because it's not clear to my which version of BASIC this is. Like here
Line 21 in 4e69cfe
GETMOUSE command for the mouse support. Since my last BASIC was the PET-CBM Basic (Commodore VIC-20), I'm little away from recent Visual Basic releases etc. Not sure, but GWBasic should not have this command too.Not sure how helpful this is, but I used to be pretty hard into qbasic, and part of the community I was apart of imported the help files onto the web. Obviously this isn't the exact flavour of basic that wwwbasic follows, but it might be a good starting place for people not familiar with *basic.
@mrozbarry thank you! gosh I have completely forget QuickBasic!!
Yeah, my main BASIC is TI-BASIC for the TI-83+ line so it's a bit weird to me as well.
Found a good reference for those still interested:
https://robhagemans.github.io/pcbasic/doc/
Docs are a good goal, assuming I'm not able to converge on full compat with something else
For the moment it hews to a weird intersection of enough basica/gwbasic compat to run donkey (which uses a few odd PEEKs and assumes the format GET/PUT use), and enough of FreeBasic to run this oldish simulator http://ed-thelen.org/NikeSimulation.html
Gorilla.BAS is next on my list, as it will fill out more of the structured constructs.
To clarify, qbasic support is in scope (as freebasic supports it), but right now a bunch of cherry picked freebasic things like getmouse and some of its modes are there, but major things are missing like: functions and subroutines.
WIP toward that here:
https://github.com/google/wwwbasic/tree/functions
I go to file issues on the gaps...
I'd like to assist in this project. Is there a documentation, guidelines, or process flow charts show how javascript processes each line and handles memory? Is there a list of functions from the PC-BASIC documentation and implementation status so that we can easily see what work needs to be done?
Help would be awesome!
In terms of documenting what the JS does, it's fairly dense, somewhat on purpose.
The best way to capture state of what works is probably the tests, although I unfortunately started filling them out too late in the process, so they have bad coverage.
At this point, a quick script can probably extract which keywords in the grammar at least have coverage (I might go try that a sec now). A bunch of it will be pretty easy to tag as to what work, as I probably can mark at a glance which ones were don't partway, all the way, or just parsing but not working.
The harder this is getting a handle on what's missing (as we'd have to go dig up a good list).
For BASICA, I would imagine the list of keywords here would be a decent start:
https://archive.org/details/IBMBASICAV1.10Manual
For GWBASIC and QBASIC things seem a little harder to come by.
QBASIC has its own fairly nice built in reference manual, firing it up and gathering that list would be nice.
Other option is lean on Freebasic or QB64 might be ok.
Biggest general issue is wanna make sure we're on a good footing in terms of copyright.
Gonna go get that extracted list...
Here's a dump of tokens currently understood (parsed anyway), FWIW:
&
&=
(
)
*
*=
+
+=
,
-=
.
/
/=
0
1
2
:
;
<
<=
<>
=>
=
\
\=
\n
^
^=
and
any
as
b
base
beep
bf
call
case
chain
circle
close
cls
color
const
data
declare
def
defdbl
defint
deflng
defsng
defstr
dim
do
draw
else
elseif
end
error
exit
explicit
f
for
function
get
getmouse
gosub
goto
if
input
integer
key
line
locate
loop
mod
next
not
off
on
open
option
or
output
paint
palette
play
poke
preset
pset
put
randomize
read
redim
rem
restore
resume
return
screen
seg
select
shared
sleep
sound
step
sub
swap
system
then
to
type
until
using
view
wend
while
width
xor
{
}
It's a fair point some functions could benefit from proper docs strings.
I'd instinctively resisted for the same reason I'd avoided mergers, minifiers, and packagers: not worth the overhead for a small person chunk of code.
But as I've now got other folks eager to pitch in :-), that doesn't scale. So...
I think in terms of doc strings, we'd get the most benefit from closure style:
https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler
As then it also can help the minifier produce better code.
So for your example:
/**
* Create a byte array containing the pixels for bold 16px monospace font scaled to height.
* @param{number} height Height of the font.
* @param{!CanvasRenderingContext2D} ctx Graphics context.
* @return {!Uint8Array} Buffer containing font data of size 256*8*height.
*/
function RenderFont(ctx, height) {
}
There's tooling that can extract such things for documentation generation, but the trouble is that the functions in compiler don't directly line up with implemented functionality.
In terms of co-mingling docs with code, the tests might be a good place for that. But unsure.
WDYT?
Hi Thomas,
I got your PLAY + SOUND change to run, snazzy!
Let's work on getting that in.
I've started a separate issue for PLAY + SOUND here so we don't cross the topic streams:
#35
Cheers