SBASIC / SuperBASIC Reference Manual Online

A collection of QL services and websites.
User avatar
NormanDunbar
Forum Moderator
Posts: 2249
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: SBASIC / SuperBASIC Reference Manual Online

Post by NormanDunbar »

I have added some new docs to the Sinclair QL Github repository, and linked them to ReadTheDocs in a manner similar to the Online Super Basic Manual. These docs explain a bit about the processes and software to allow updates to the afore mentioned manual.

The docs are at http://updating-superbasic-manual.readthedocs.io/ but there appears to be a bug in that images are not showing up when online, but they do when I build locally. Sigh. I'm working on it but the first draft is available now.

If anyone is interested of course!


Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
NormanDunbar
Forum Moderator
Posts: 2249
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: SBASIC / SuperBASIC Reference Manual Online

Post by NormanDunbar »

I fixed a minor bug in the Keyrow page at http://superbasic-manual.readthedocs.io ... tml#keyrow as all 4 of the arrow keys had gone missing from row 1.

I suspect this was because the original source had the actual arrow characters, but they somehow got stripped out in conversion. I fixed a number of similar problems during the conversion - I must have missed this one.

Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
NormanDunbar
Forum Moderator
Posts: 2249
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: SBASIC / SuperBASIC Reference Manual Online

Post by NormanDunbar »

This arrived in my inbox tonight:
Hi,

We wanted to make you aware that on Saturday August 18 at approximately 10:00am PDT (1:00pm EDT, 17:00 UTC), Read the Docs will be having a scheduled downtime of approximately 4 hours. During this time, we will be moving our service to our new home on Microsoft Azure.

To ensure the stability and performance of our system, we are performing this upgrade during the weekend which is our period of lowest usage.

During this maintenance window, documentation will still be serving but new documentation builds will not trigger and the Read the Docs dashboard will not be available. New builds and webhooks will begin processing once the maintenance is over.

For more details, see our blog post: https://blog.readthedocs.com/azure-migration/

Sincerely,
The Read the Docs team
This all means that the SuperBasic Online Manual will be offline as far as updates and new builds are concerned, during the maintenance period. It should still be readable.

Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
NormanDunbar
Forum Moderator
Posts: 2249
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: SBASIC / SuperBASIC Reference Manual Online

Post by NormanDunbar »

Afternoon All.

I've had a bit of spare time so, rather than "having a life" (as Mrs D would say) I've been working away trying to finish all the TODO tasks for the Online SuperBASIC manual.

These have, as far as I can see, all been completed, as have a number of spelling corrections, grammar corrections, some table layouts were corrupted in the PDF version of the manual - those are now also fixed.

There's still a few things to do, but until I get my finger out (technical term) to create an easy manner of updating the manual, what you see is what you get!

As ever, it can be found at:

http://superbasic-manual.readthedocs.io/en/latest/

And you can fork the source code from:

https://github.com/NormanDunbar/SuperBASIC-Manual

Should you wish to make any amendments.


Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
RWAP
RWAP Master
Posts: 2833
Joined: Sun Nov 28, 2010 4:51 pm
Location: Stone, United Kingdom
Contact:

Re: SBASIC / SuperBASIC Reference Manual Online

Post by RWAP »

Thanks Norman :D


User avatar
Cristian
Aurora
Posts: 960
Joined: Mon Feb 16, 2015 1:40 pm
Location: Veneto

Re: SBASIC / SuperBASIC Reference Manual Online

Post by Cristian »

Thank you very much!


User avatar
NormanDunbar
Forum Moderator
Posts: 2249
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: SBASIC / SuperBASIC Reference Manual Online

Post by NormanDunbar »

I'm doing a bit (a lot) more tidying up of the online manual, and here's a list of what I'm looking at right now:
  • [1] Getting all the toolkit names (ie, Locations) standardised. We have things like "QLROM" and "QL ROM" etc.
    [2] Maybe adding a page for each/some toolkits so that there is a list of links to the functions and procedures in that specific toolkit. Someone asked for this a while back. This might not happen yet though.
    [3] Reorganising the source so that instead of all the 'A' keywords being in one file, for example, there's a separate file for each individual keyword. This is so that the soon to come manual updater can do a better job.
    [4] Getting rid, well, compressing, the old HTML files of Rich's original online manual and all the working files that were created as part of the conversion.
    [5] Make sure all mentions of a keyword in any descriptive test etc, is converted to a link to that keyword. (Long term ambition!)
    [6] Etc etc etc.
Number [4] above is done and dusted. So is number [3] in the main, but in doing so, I've come across a small foible.

When we currently look at a page, we get the entire set of keywords beginning with the same letter, so looking for ALPHA_BLEND for example, gives you the page with everything from ABS to A_SPEED and it's easy to scroll around, or simply browse the keywords.

However, because I've now got things set up with each keyword in it's own file, that constitutes a page, and while the page loads far quicker now - there's much less to load - browsing or scrolling around the other keywords is not as easy. However, to my mind, it's better and more efficient - I'm looking for a particular keyword, that's fine, I'm not really interested in the others alphabetically around it. Is this something that might irritate you? Do you browse the manual, or look up specific keywords (the latter is my MO) - just wondering.

I don't have an online version with the changes yet, but rather than do all the work and have to undo it again, I thought I'd better check first.

EDIT: Ha! I found an option that gives next and previous buttons at the bottom of each page. I have enabled those on the test system and it's perfect. Browsing is back!

Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
RWAP
RWAP Master
Posts: 2833
Joined: Sun Nov 28, 2010 4:51 pm
Location: Stone, United Kingdom
Contact:

Re: SBASIC / SuperBASIC Reference Manual Online

Post by RWAP »

NormanDunbar wrote:
However, because I've now got things set up with each keyword in it's own file, that constitutes a page, and while the page loads far quicker now - there's much less to load - browsing or scrolling around the other keywords is not as easy. However, to my mind, it's better and more efficient - I'm looking for a particular keyword, that's fine, I'm not really interested in the others alphabetically around it. Is this something that might irritate you? Do you browse the manual, or look up specific keywords (the latter is my MO) - just wondering.

EDIT: Ha! I found an option that gives next and previous buttons at the bottom of each page. I have enabled those on the test system and it's perfect. Browsing is back!
The Next and Previous buttons are essential - maybe an overall index too would help - such as
[2] Maybe adding a page for each/some toolkits so that there is a list of links to the functions and procedures in that specific toolkit. Someone asked for this a while back. This might not happen yet though.
The problem is where there are keywords similar to each other which are used together - such as PARUSE and PARTYPE - but because they don't always begin with the same letter, so long as the hyperlinks work, that is better :)


User avatar
NormanDunbar
Forum Moderator
Posts: 2249
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: SBASIC / SuperBASIC Reference Manual Online

Post by NormanDunbar »

Hi Rich,

yes, the next and prev buttons are a godsend. I've noticed that they actually exist online at the moment, but not on my test build. However, I've updated the theme on my test bed, because the latest one didn't allow searching - it just sat there saying it was searching, but wasn't doing anything. I'm wondering if the latest theme files did away with the navigation buttons.

As for an overall index, there's already something that passes for one, it's on the left side. It's the navigation sidebar, but could be considered an overall index as all the keywords etc are listed there.

Alison has gone out for a walk with her walking friends today, so I'm playing!


Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
User avatar
NormanDunbar
Forum Moderator
Posts: 2249
Joined: Tue Dec 14, 2010 9:04 am
Location: Leeds, West Yorkshire, UK
Contact:

Re: SBASIC / SuperBASIC Reference Manual Online

Post by NormanDunbar »

Ok, a temporary test site.

Grab this file: http://qdosmsq.dunbar-it.co.uk/download ... Manual.zip It's 30.2 MB by the way. When it finishes downloading, extract it somewhere safe. It will create a folder called html. In there you will find index.html - open that in your browser.

That file will remain for a few more days, maybe a week. Then it will be gone. (I need the disc space!)

See what you think. If you don't see a lot of difference then things are pretty much ok. You'll know it's the new version by there being "next" and "prev" buttons on the top and bottom of every page, individual pages load far quicker than before, and there's a small QL logo in the top left corner.


Cheers,
Norm.


Why do they put lightning conductors on churches?
Author of Arduino Software Internals
Author of Arduino Interrupts

No longer on Twitter, find me on https://mastodon.scot/@NormanDunbar.
Post Reply