Page 3 of 7

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Fri Jan 06, 2017 10:29 pm
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.

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Sat Mar 17, 2018 5:57 pm
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.

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Mon Aug 13, 2018 10:23 pm
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.

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Tue Dec 04, 2018 4:15 pm
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.

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Tue Dec 04, 2018 4:45 pm
by RWAP
Thanks Norman :D

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Tue Dec 04, 2018 8:10 pm
by Cristian
Thank you very much!

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Thu Dec 06, 2018 11:51 am
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.

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Thu Dec 06, 2018 12:15 pm
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 :)

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Thu Dec 06, 2018 12:21 pm
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.

Re: SBASIC / SuperBASIC Reference Manual Online

Posted: Thu Dec 06, 2018 1:17 pm
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.