SBASIC / SuperBASIC Reference Manual Online

[pjw]

Nice work, Norm!
Might be a good idea to refresh the old RAM again, by going through the list! However, it doesnt look like the list has been updated since about SMSQ/E V2.99. (Probably my fault for not doing my bit.. )

[pjw]

Heres a wee taster:

Code: Select all

(SMSQ/E)
3.34
JOB_NAME         - Updated: works for compiled tasks too. Can
                  change name at any time (like QPAC2 Files). Up to 48 char.
SUSJB         - Suspend a job for a given number of ticks.
                 -1 => infinite. Same parameters as other
                 TK2 job commands. (Also in TK2 2.32)
FDEL            - Function versions of DELETE (may not have
                  made it into 3.34 and TK2 2.32)

3.30
JVA_IS_QLSCREMU%
DISP_MODE       - Q40

3.28
JVA_VER$          - Java
JVA_WINDOWTITLE
JVA_NETNAME$

3.24
JVA_SCRUPDT       - (Java)
JVA_MBAR_STATUS   - (Java)

3.22
FEX_M         - Function version of EX_M (see below)

3.16
WM_MOVEALPHA   - Move/Copy a block of screen data with
              alpha blending
3.13
YEAR%, MONTH%, DAY%, WEEKDAY%

3.12
PEEK_F, POKE_F
PEEKS         - PEEK supervisor
JOBID         - Job ID. Same parameters as for other TK2
                job commands

3.09
GET_HOTSTUFF$   - function to get strings from stuffer
                buffer. 0 => current, -1 => previous

3.07
EX_M            - EXECute file with me as owner. Like
                EXEC_W, but without the _W

3.06
QUIT            - Takes optional error code parameter. Eg
                er = FEW(mylittle_job). If mylittle_job quits with QUIT -15, er = -15.

3.00
FEX, FEW, FET      - Function versions of EX, EW, ET. FEX and
                FET return ID of (first) job in a chain. FEW returns any error from job.

Unknown when introduced:
WM_PAPER      - the following 5 keywords use the Window
WM_STRIP             Manager palette colour codes
WM_INK
WM_BORDER
WM_BLOCK

WM_MOVEMODE   - parameter 0..3. Different ways of moving a
                window, from the old-fashined move an icon, to moving a semi-transparent window.


SP_GETCOUNT      - Get number of palette entries (currently 57)
SP_JOBOWNPAL      - Set a job's private palette (address)
SP_JOBPAL      - Set a job to use a system palette, 0..3
SP_GET         - SP_GET [number,] address, first, count
                     Gets the colours from a system palette and puts them somewhere.
SP_SET         - SP_SET [#channel,] [number,] address, first, count
              Sets the system palette entries
SP_RESET         - SP_RESET [#channel] [,number]
               This resets the colour palette given in number to the original values (as
               configured). Default is number 0.


References: SMSQ/E Changes log, README.pdf from SMSQmulator,
QPC_Keywords.pdf from QPC2, display_txt and other documents in the SMSQ/E extras directory.
None of these references are complete or entriely up to date!

Im not for a moment suggesting that you (Norman) put this right! But there obviously is a job to be done (if "we" want a complete and up-to-date reference work on S*BASIC).

[NormanDunbar]

I'm working on an assembler utility for the next Assembly 'eComic', that will allow easy creation of keyword details for the online manual.

Hopefully, I'll get it finished and tested "soon".

I have also been sent some updates that cover some of what is listed in your post.


Cheers,
Norm.

[NormanDunbar]

Afternoon All.

The SuperBASIC Online Manual has been reformatted and much work has been done to tidy stuff up. I have not yet put this live, but if you go here https://superbasic-manual.readthedocs.io/en/working/ then you will be able to view the latest manual style.

It looks remarkably similar to the old version but:

• I've split the keywords into files of their own. This improves editing, but increases build times. I can live with that especially as "ReadTheDocs" does all the live builds.
• Source files for keywords are now in alphabetic folders.
• Frontmatter is in a Frontmatter folder.
• Appendices are in the Appendices folder.
• Spelling, grammar and broken links are fixed.
• Syntax tables are fixed for best results on HTML - for online viewing, or PDF - for printing (too many pages to print!)
• A new Toolkits page has been added at https://superbasic-manual.readthedocs.i ... lkits.html - you can now browse the commands in each individual toolkit.
• We have a logo! Top left of the page there's a QL image.
• Scrolling of the left sidebar is fixed. It was apparently a random scroll as you viewed a page. Now it remains steady until you scroll it. Much better.
• Every page has NEXT and PREV buttons, top and bottom.

Still to do?

• Make sure that the toolkit names in the individual keyword pages are standardised. We have, for example, 'Tiny Toolkit', 'TinyToolkit' and 'Qview TinyToolkit' - presumably all for the same toolkit? I've assumed this to be the case in the Toolkits page, and merges them all under TinyToolkit at https://superbasic-manual.readthedocs.i ... inytoolkit.
• Someone who isn't me, and who knows these things, needs to have a look at the 'SMS', 'SMSQ', 'SMSQ/E' and 'SMS* For Whatever' on the Toolkits page to make sure I've got it correct.
• Ditto for the 'Atari' and possibly 'Amiga'/'ST' stuff.
• I need also to incorporate the files that ToFro sent me, with some updates. Thanks Tobias, I'll get the merged as soon as I can.

If there are no complaints in the next couple of days, for certain values of 'couple' and 'days', then I'll merge the working branch into the master branch and bring the main ReadTheDocs location up to date.

In case you are wondering, I have two branches in my repository on GitHub - master and working. I normally do changes in working and push them back. ReadTheDocs then notices and does a build. I check the build as best I can, and if ok, merge the changes into the master branch. That merge then kicks off another build on ReadTheDocs, this time of the master (aka latest) version of the docs.

If you look at the bottom of the left side of the screen you will see "Read The Docs" and "V:latest" - click that, and you can look at HTML, PDF or EPUB for the docs in either the Latest or the Working versions. You can also have a look at recent builds to see how up to date the docs are etc. Downloads are available of all versions in the three formats, so Derek might want the EPUBs while I'm more likely to partake of the PDF files. HTML is there too - if you want a local version of the online stuff. (The direct link to the downloads page is https://readthedocs.org/projects/superb ... downloads/)

[pjw]

Looking very good, Norm!
I think you should also include the Q-Liberator toolkit and, IMHO, the various EasyPTR toolkits, since they now are PD and very much part of the modern cannon. Dont know about the status of Qptr..
Theres probably no way to automate this, but one thing that might considerably augment the usefulness of this documentation as a programmer's tool, would be to, under each keyword, list and link any synonymous keywords found in other toolkits. This so that one could make an informed decision as to which toolkit(s) to use. After all, theres little point in loading three toolkits with your program if all the keywords you need are found in just one - or already exist in your target platform! Perhaps save that for a later version..

[NormanDunbar]

If people send me a text file with the toolkit details and description etc, I'll build it in to the manual.

There's already a cross reference at the bottom of each page but I suspect that it may need updating.

Submissions gratefully received!


Cheers,
Norm.

[tofro]

I'm not sure if EasyPtr (and QPTR) should actually go into the S*BASIC reference manual - They have (pretty good) manuals of their own and I somehow feel a full introduction into PTR programming might be well beyond the scope of the S*BASIc manual.

Tobias

[pjw]

I'm not sure if EasyPtr (and QPTR) should actually go into the S*BASIC reference manual - They have (pretty good) manuals of their own and I somehow feel a full introduction into PTR programming might be well beyond the scope of the S*BASIc manual.

Im aware of your point , Tobias. I just think that the selection of keywords and toolkits in the manual is somewhat lopsided, and underrepresents lets say, a different outlook on what S*BASIC programming is or can be. Why is the Turbo toolkit in and QLib out? A number of post-V2.99 SMSQ/E keywords have made it into the manual, but others have not. Im not suggesting that these are deliberate choices, just that in total, they represent a "view". PI and Wman are now part of the "QL", ptrmen and Qptr are the only toolkits that make these systems accessible to many S*BASIC programmers. A number of rather arcane and obscure toolkits have made it into the manual, presumably in a bid to make it a comprehensive, if not THE definitive, manual. If that is the case, omitting these important system extensions would be odd, IMHO.

[RWAP]

• Make sure that the toolkit names in the individual keyword pages are standardised. We have, for example, 'Tiny Toolkit', 'TinyToolkit' and 'Qview TinyToolkit' - presumably all for the same toolkit? I've assumed this to be the case in the Toolkits page, and merges them all under TinyToolkit at https://superbasic-manual.readthedocs.i ... inytoolkit.

No - there is the Tiny Toolkit and a separate Qview TinyToolkit.

I have realised that the programs Q-Help and Q-Index do not seem to be on Dilwyn's site - these are attached (together with the sources).

I also attach all of the public domain toolkits covered in the Reference Manual - some of these may need adding to Dilwyn's site also

These files are all zipped on the QL

[RWAP]

I'm not sure if EasyPtr (and QPTR) should actually go into the S*BASIC reference manual - They have (pretty good) manuals of their own and I somehow feel a full introduction into PTR programming might be well beyond the scope of the S*BASIc manual.

Im aware of your point , Tobias. I just think that the selection of keywords and toolkits in the manual is somewhat lopsided, and underrepresents lets say, a different outlook on what S*BASIC programming is or can be. Why is the Turbo toolkit in and QLib out? A number of post-V2.99 SMSQ/E keywords have made it into the manual, but others have not. Im not suggesting that these are deliberate choices, just that in total, they represent a "view". PI and Wman are now part of the "QL", ptrmen and Qptr are the only toolkits that make these systems accessible to many S*BASIC programmers. A number of rather arcane and obscure toolkits have made it into the manual, presumably in a bid to make it a comprehensive, if not THE definitive, manual. If that is the case, omitting these important system extensions would be odd, IMHO.

The reason for this is historic and remember I was the only person updating and adding to the SBASIC/SuperBASIC Reference Manual for many years. It was originally intended to only cover the basic operating system and not include ANY commercial toolkits as that would have been seen as promoting other people's products.

I started adding Turbo Toolkit (probably after it became public domain) but I am not sure that I ever finished - sales of the Reference Manual had actually stopped and no-one was buying updates for the printed version. QLiberator remained a commercial product until quite recently. SMSQ/e was not updated in the manual because I was lacking documentation on the latest keywords. WMAN, Pointer Environement, Ptrmen and Qptr were also only public domain in recent years (after I stopped updating the manual) and to be honest, explaining how to use the Qptr toolkit commands was beyond me as the original manual was highly confusing!

The SBASIC/SuperBASIC Reference Manual was turned into a community project in June 2016 - so that is 2 1/2 years where people could have added all of these missing details.

So the short story is - yes, let's make it THE definitive manual. However, you all need to contribute if it is to become that!