Feature Request: HELP shouldn't be a syntax error! :)

[Tatwi]

I've always thought this was an oversight on the Commodore machines. If you don't happen to have the manual handy, the machine doesn't help know how to use it at all. Personally, this was a problem for me when I inherited a C64 in my early teens - not having any books for it or any friends/mentors to assist, I just stopped using the machine after a short time. I don't even remember what happened to it (this was the late 1980s though).

Anyway, it would be nice if HELP was a BASIC keyword that would provide an information system similar to that Microsoft QuickBasic 4.5. The reference text would be more than what could fit into the standard ROM, so what if the HELP program requested the user provide it with the HELP.DAT file, by inserting the Help disk (image)? That's not immediately useful to the user, but it is a clear step the user can take towards helping themselves and it's more use informative than a Syntax Error message.

Clearly this isn't required in today's day and age, where everyone has the Internet at their finger tips, but if we're thinking like that, then the Commander X16 itself isn't necessary either, because there are already so many other devices and emulators available. However, if we think about the Commander X16 as a self contained system, I think it would be nice if there was a HELP command built into the machine.

[Kroc]

Also, typing HELP <KEYWORD> would return a simple one-line description/example of a BASIC keyword, e.g. HELP PRINT

[bobbyjim]

GRANTED, sometimes you just want the syntax for a BASIC command. You'll reach for the reference manual and look it up. Maybe that has value right on the hardware or tucked somewhere useful. Just Maybe.

But, this isn't the 80s anymore, and we have vast, easy to access resources.

So, help me understand the use cases here. What are the circumstances today under which you would need this?

Now getting past that, I'd probably want whatever fits into the smallest footprint. The X16 ABI has compression routines, which might help.

Probably, it would have all supported BASIC commands with a very brief synopsis of usage, such as

ABS(n)
AND; boolean or bitwise
ASC(c$); PETSCII value
ATN(n); arctangent
CHR$(n); PETSCII char
CLOSE <logical filenumber>
CLR; delete all vars, arrays, data, fns, return addresses, opened files
CMD <logical filenumber> [, string[;]]; changes output device
CONT; resume execution from end or stop
COS(n); cosine
DATA <constant> [,...]
DEF FN <name>(n)=<mathematical expression>
DIM <var>(d1)[(d2)[(d3)[...]]
END; halt execution
EXP(n); e to the n-th power
FN <name>(n); invoke defined function
FOR <var> = <n1> TO <n2> [STEP <n3>] [<code>] NEXT
FRE(n); freemem.  n is a dummy.
GET <var> [,<var>...]; read char from keyboard cache
GET# <logical filenumber>, <var> [,<var>...]; read char from logical device
GOSUB <line>
GOTO <line>
IF <expr> THEN <line or command>
IF <expr> GOTO <line>
INPUT ["<text prompt>";] <var> [,<var>...]
INPUT# <logical filenum>, <var> [,<var>...]
INT(n); round down
LEFT$(string,int n); return leftmost n chars in a new string
LEN(string); string length
LET <var>=<rvalue>
LIST; lists BASIC program
LOAD "<filename>"; load file starting at $0800
LOG(n); natural log
MID$(string,int pos, int len); return len chars starting at pos in a new string
MID$(string, int pos); return new string from pos to end of source string
NEW; releases BASIC RAM and the stack.
NOT boolean or bitwise
OLD; undoes NEW. Must be issued immediately after NEW.
ON <index> GOSUB|GOTO <line> [,<line>...]
OPEN <logical filenumber> [,<device num> [,<secondary num [,"filename[,<type>[,<mode>]]"]]]
OR logical or bitwise
PEEK(addr)
π; 3.14159265
POKE addr, value
POS(n); cursor pos; n is a dummy value
PRINT
PRINT# <logical filenumber>, <var> [, <var>...]
READ <var> [,<var>...]; read from DATA
REM
RESTORE; resets the pointer of the next DATA value
RETURN
RIGHT$(string,len); returns a new string with the rightmost len characters.
RND(0); rand number from the clock
RND(1); rand number from a seed
RND(n); seeds the generator (n is a negative number)
RUN
SAVE "filename" [,<device> [, <secondary number>]]
SGN(n); -1 if negative; 0 if zero, +1 if positive
SIN(n); sine
SPC(n); print n spaces
SQR(n); square root
ST; system status
STATUS; see ST
STOP; halts execution
STR$(n); stringifies number
SYS addr; call machine language at addr
TAB(n); set cursor logical screen column
TAN(n); tangent
TI; time, in jiffies
TIME; see TI
TI$; time in HHMMSS format
TIME$; see TI$
USR(n); call user-defined machine language routine, returning a float.
VAL(string); return numerical value of string
VERIFY ["filename" [, <device num>]]
WAIT <address>,<and-bitmask> [,<or-bitmask>];

[Kroc]

For the reason that the X16 is being made in real hardware rather than just an emulator, some people want to code on the hardware and get away from all the distraction of modern PCs. Having everything you need on the X16 itself just makes the experience so much better.

[bobbyjim]

Well now, that's different from the use case from the original post. The original poster's use case was a teenager in the 80s wanted to code, but couldn't because he lacked access to references. That use case no longer exists.

Perhaps your use case is: some people want to code on the X16 without any modern anything, and without any manuals. Manuals can be lost; why depend on them?

So two things get in my way about this: one about experience and access, and one about usability.

(1) Experience and Access. Surely a genuine experience includes the printed manuals, which solves the help problem AND the readability problem AND the distraction of modern hardware. And granted, manuals can be lost -- even X16 manuals. But if someone has to stoop to displaying a PDF on a tablet, will that truly ruin the experience?

As for access to manuals: I would suggest if one loses the manuals, but one's goal is to be strictly retro, then one can still validly print out the manual from PDF -- or even just a two-sided cheat sheet -- and one is back in action. Only a minor diversion into the modern world, quickly remedied, easy to do... certainly a LOT better than 1985, when one might not have been able to find a manual.

So, I'm not quite convinced for a HELP program.

(2) Usability. The original ask was for a HELP routine that would read from a file, presumably without destroying BASIC memory. Sort of like man pages, perhaps. I can see it, but... I'm really having trouble seeing how useful that is compared to a physical manual. Consider that the BASIC commands that are really subtle need to be there while we're working. If we flash to a description then that goes away, we won't remember it.

For example, you're trying to refer to the OPEN statement, so you type HELP and it queries for the HELP DISK. So you insert the SD card for HELP. And then you find the OPEN statement, read it, and.... what then? Close the window, re-insert the original SD card, and try for the life of you to remember what you just read? Maybe you have to boot it up again and re-read it? Maybe you have to jot down what you saw so you don't mix things up? How is this better than a physical manual turned to the page for OPEN?

• • • BORING SUMMARY TO MY BORING POST *

My apologies.

I do sympathize with the young teen in the 80s who had no access to references, and therefore was frustratingly lost. I would have hated that. But, we are not living in the 80s, and his access to reference problems are gone.

And I understand that there is severe nostalgia in working off of the hardware -- that's why we're all here really. We want a bit of that youth back, and the rush of our first programming years. But there's no need to go paleolithic about it. I strongly suspect 99% of us own modern computing hardware, and will not give it away when the X16 comes out.

[bobbyjim]

Having raved for a bit, I'll now note that a very short definition of BASIC2 commands takes under 3K, and zipped it takes maybe 1.6K.

So a light reference app run by a HELP command is doable within an 8K ROM.

[Tatwi]

For the reason that the X16 is being made in real hardware rather than just an emulator, some people want to code on the hardware and get away from all the distraction of modern PCs. Having everything you need on the X16 itself just makes the experience so much better.

That's exactly what I was thinking.

If you're just going to program for X16 using a modern PC, then why even bother making the X16 at all. There are already an endless amount of options to program on the PC.

Personally, I will never be able to afford an Commander X16, but if I did get one I would sit at it and use it. Just it.

[Kroc]

The grander issue is that perhaps the system needs better out-of-the-box support for TSRs, so that a background help application could be loaded, and a keypress could consult the manual. That can then be put on the SD-card, and the KERNAL doesn't have to include that stuff.

[tomxp411]

I think the HELP text would take up far too much memory to be memory resident... but you could parse the help files from disk. A basic viewer wouldn't be more than a few hundred bytes, and the text can be as long as necessary, since it would be a series of files stored on the SD card.

HELP shows this list and explains how to LOAD and RUN a program. HELP COMMANDS lists BASIC commands. HELP lists the help page for a specific command. HELP MEMORY shows the memory map and useful memory locations. HELP GRAPHICS shows commonly used graphic modes and how to set them. HELP SOUND shows how to make noise with the sound chips. HELP DISK lists the disk commands and how to open and use sequential files.

[BruceMcF]

It might take even fewer bytes in the Basic ROM segment, if it is a call to the planned built in menu in its own ROM segment ... so long as the menu includes a file viewer options, which it ought to do ... which brings up a menu in the file viewer displaying a Help file directory. If there is an "extended view" option which gives one filename per line followed by the first part of the first line of SEQ file, then jumping directly into that mode in the Help file directory could give the above in very few bytes on the part of the Basic ROM.