Language Documentation

[loretoparisi]

Please add the WWWBasic language documentation.

[trn1ty]

I think it might be based on IBM PC-BASIC but a reference would definitely be helpful.

[loretoparisi]

@RandomGuyDTB thanks, I was wondering because it's not clear to my which version of BASIC this is. Like here https://github.com/google/wwwbasic/blob/4e69cfe817b410d78daa552c76faaf088198cfc8/examples/mouse.html#L21 you have the 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.

[mrozbarry]

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.

[loretoparisi]

@mrozbarry thank you! gosh I have completely forget QuickBasic!!

[trn1ty]

Yeah, my main BASIC is TI-BASIC for the TI-83+ line so it's a bit weird to me as well.

[trn1ty]

Found a good reference for those still interested: https://robhagemans.github.io/pcbasic/doc/

[flagxor]

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.

[flagxor]

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

[thomasmcneill]

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?

[flagxor]

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

[thomasmcneill]

I did a quick speed read on it and figured out the methods. At first I forgot it wasn't interpreting and then it hit me that it was converting "Compiling" to JS. Actually seems much easier to implement than a line by line interpreter.

Is their a preferred style for function documentation? Example: /** Returns a byte array containing the pixels for bold 16px monospace font scaled to height

@height; height of the font
@ctx:  graphics context
@return: Uint8Array of size 256*8*@height

*/ function RenderFont(ctx, height) { ... }

On Fri, Sep 21, 2018 at 11:35 PM Brad Nelson notifications@github.com wrote:

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

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/google/wwwbasic/issues/6#issuecomment-423713509, or mute the thread https://github.com/notifications/unsubscribe-auth/AOPhswYAq7s9nU6pyFiXYmwq9UzndDbeks5uda_zgaJpZM4WreoB .

[flagxor]

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 print 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 { }

[flagxor]

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?

[thomasmcneill]

I am kind of new to using GitHub. I have sound and beep working. I pulled the branch called functions. I think I mistakenly made a pull request via the web but don't want to delete it in case it does something unintended on my part.

I committed my changes locally but I got access denied trying to push them.

Thanks

On Sat, Sep 22, 2018 at 2:08 AM Brad Nelson notifications@github.com wrote:

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 2568height. */ 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?

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/google/wwwbasic/issues/6#issuecomment-423719820, or mute the thread https://github.com/notifications/unsubscribe-auth/AOPhs1Pk4QZ_QyUkGXyarWOpoWRgGKSBks5uddPggaJpZM4WreoB .

[flagxor]

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: https://github.com/google/wwwbasic/issues/35

Cheers

[thomasmcneill]

Thanks. Long long time ago I used to write programs to play ScreamTracker and MOD files. It wasn't a far stretch to apply it to JS. Although I need to implement background mode. To do background mode I'd need to make a queue/list and set a timer to elapse play the next item in queue.

Thomas

On Mon, Sep 24, 2018 at 12:33 AM Brad Nelson notifications@github.com wrote:

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 https://github.com/google/wwwbasic/issues/35

Cheers

— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/google/wwwbasic/issues/6#issuecomment-423875151, or mute the thread https://github.com/notifications/unsubscribe-auth/AOPhs4XPPySasVUrGnctoSIzpX21i_3hks5ueGChgaJpZM4WreoB .