Knoware.no

Anything QL Software or Programming Related.
Tinyfpga
Gold Card
Posts: 252
Joined: Thu Sep 27, 2018 1:59 am

Re: Knoware.no

Post by Tinyfpga »

Thanks to Norm and pjw for their advice. I now understand that VALID% will not do what I wanted it to do. I have started testing other instructions in your tool kits. So far I have tried JUST$ which,I am sure, will prove useful.

The only way I can understand what an instruction does is to test it to destruction, and destruction, including destroying
SMSQ/E, is a regular occurrence. I think that I may be a literalist and so I often make mistakes when writing software.

Many times I have no idea what a manual is trying to "say". An example of my problem is as follows:-

s$ = JUST$(jst%, width%, text$)
Justify text in a field

I immediately ask myself:
What is a field? Where is it. Where does it start and end. Do you have to create it. Can a field be in a file. What is s$

I always write to a predefined consul or screen. I never use the interpreter (except for my BOOT program) and thus
I think "what would the following line actually do":-

At #2,1,1 : Print #2,JUST$(1, 20,"123.56")

By the way these questions are rhetorical. I need no reply. I have tested the instruction in a way I can understand and it works fine.

I know it is very difficult to write an instruction manual such that anyone can understand it. Just try understanding the instruction manual for a WIFI enabled timed thermostat. (This is something I have to do a lot. I regularly suggest that the damn thing should be replaced with a simple dial control)
Last edited by Tinyfpga on Tue Oct 19, 2021 1:39 pm, edited 5 times in total.


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

Re: Knoware.no

Post by NormanDunbar »

tinyfpga wrote:By the way these questions are rhetorical. I need no reply.
I was just about to start typing ...... ;)

Code: Select all

s$ = JUST$(jst%, width%, text$)
Justify text in a field
Just wondering, what would you expect to see in the docs for such a construct? I write stuff, manuals, even a book, but I'm interested in knowing what you think. Obviously, some context about the original instruction is missing, and I can see where I would not have used "field" as the code returns "a string", but what would you expect that to say?


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.
Tinyfpga
Gold Card
Posts: 252
Joined: Thu Sep 27, 2018 1:59 am

Re: Knoware.no

Post by Tinyfpga »

Norm writes;-Just wondering, what would you expect to see in the docs for such a construct?
You ask a difficult question which I will answer later. (I have no time right now). The problem may lie in the fact that those who know are often cleverer than those who don't.
I am clever enough to write simple application programs but only just. Writing software that works is difficult but I enjoy doing it all the same. A bit like I enjoy playing musical instruments ( I am similarly useless at that).

My SMS programming environment was designed to be "easy to use" but even that is really difficult to explain because there is so much to it. Writing manuals for "dummies" is, I imagine, tedious for those that can do it.
Last edited by Tinyfpga on Thu Oct 21, 2021 7:28 pm, edited 1 time in total.


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

Re: Knoware.no

Post by NormanDunbar »

No worries. I'll be interested as it might help make the writing I do better.

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
pjw
QL Wafer Drive
Posts: 1286
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Knoware.no

Post by pjw »

Im sorry, guys, that my "manuals" are so obtuse. I think in English but live in Norway, so I find it harder and harder to find the right words in either language. It may settle, eventually.

That being said, I think TT's manuals are even more obtuse than mine! But hes a genius, so one cant really complain. The thing with his manuals is that once, after much toil and tears, and rending of garments, you understand the underlying material, it becomes crystal clear (the bits you already understand, that is) so then you see that that is what he was saying with perfect clarity all along!

I cant, obviously, hope to achieve that effect, nor do I have that "for dummies" ability to make myself understood from the start, so my advice is: Experiment! Try and fail and try again until you figure it out. Its software, after all. THEN read the manual again and see if it agrees with your experience (and let me know if it doesnt!) It seems that is what Tinyfpg has done, so good on him!

Just make sure you read the caveats, so that you dont waste hours trying to get something to work on, say a BarBieQL, that was designed to run under GD2! and the rest should be gravy.


Per
dont be happy. worry
- ?
User avatar
dilwyn
Mr QL
Posts: 2753
Joined: Wed Dec 01, 2010 10:39 pm

Re: Knoware.no

Post by dilwyn »

An author may sometimes write instructions with the intended application in mind, or based on what the original extension was used for.

So, there may be no right or wrong if someone else has another use in mind for something.


User avatar
tofro
Font of All Knowledge
Posts: 2685
Joined: Sun Feb 13, 2011 10:53 pm
Location: SW Germany

Re: Knoware.no

Post by tofro »

Agree completely that writing manuals is not fun. Writing understandable manuals is even less fun, and much more difficult. To be able to write it, you have to understand the subject, and to be able to write it well, you have to forget what you know and learn it again, then document that process ;) . Whatever assumption you make about the level of understanding of your audience is going to be wrong anyways. Teaching stuff, if done well, is a dialogue, which is unfortunately not possible with printed matter.


ʎɐqǝ ɯoɹɟ ǝq oʇ ƃuᴉoƃ ʇou sᴉ pɹɐoqʎǝʞ ʇxǝu ʎɯ 'ɹɐǝp ɥO
User avatar
pjw
QL Wafer Drive
Posts: 1286
Joined: Fri Jul 11, 2014 8:44 am
Location: Norway
Contact:

Re: Knoware.no

Post by pjw »

I miss those hefty, fat manuals of yore, yet I wouldnt have them back!
They take up too much room, are hard to search, and, of course, cant
easily be updated. No, the online solution is better for this kind of
thing.

They still need to be well written, though, and that is hard for some.
Even harder, I find, are aesthetics. I really appreciate good art, but
I couldnt draw a pimple myself, so my programs often look like shit
(viz Match!)

Feedback is a sort of dialogue, and one to which I usually respond. As
a result of discussions here I have made changes to code and "manuals".
Perhaps I dont always improve them according to the critic's lights,
but I do revisit them and try to make them better by my own.


Per
dont be happy. worry
- ?
Tinyfpga
Gold Card
Posts: 252
Joined: Thu Sep 27, 2018 1:59 am

Re: Knoware.no

Post by Tinyfpga »

I agree with Norm, pjw and Dilwyn. I rate their on-line and off-line work highly. I am not familiar with tofro's work but would like to know more. I agree with pjw's view on well written aesthetically pleasing prose. To his mix I would also add a smattering of wit, such as Norm's opening line "Assembly language is very,very simple"

Weak instruction manuals exist even where I would not expect them to. For example I was looking forward to reading the official Raspberry Pi Beginner's Guide that came with the Pi400s. It was a disappointing read.
It is "kind of" 243 pages of flannel. To be fair to Gareth Halfacree he had to provide instructions for the dire programming
environments, Scratch and interpreted Python which come pre-installed in the PI SD card. For a beginner the original QL user manual is much better. (It is what I used recently to re-learn how to write compiled BASIC programs).

I gave up trying to write an application program for the PI400 in half an hour. I could not create an independent windowing program and it became clear, very rapidly, that this was going to be impossible with the tools provided.

My SMS2 in SMSQE setup is different. With just 4 lines of code I can write an executable windowing program that does not rely on a huge pile of hidden software for support. For a recreational programmer, like me, this is encouraging. For me, there is a certain irony in the fact that the resident PI programming software is the exact opposite.

As an example of current trends in programming systems, the BBC Microbit programming environment (designed for young schoolchildren) is 168 M bytes in size. That's 300 times bigger than SMS2 with its original windowing IDE. Does it do more? I would say no. You have to be really keen to program a Microbit.

I have not got a lot of free time to play with SMS but to answer Norm's original question I have been writing some application programs incorporating the instructions JUST% and EVAL, to see if I could write some compiled BASIC programs that are easier to understand (Most unlikely). My only advantage is that I know very little and so I have to write in a way that I can easily grasp.
Last edited by Tinyfpga on Thu Oct 21, 2021 7:31 pm, edited 2 times in total.


User avatar
RalfR
Aurora
Posts: 870
Joined: Fri Jun 15, 2018 8:58 pm

Re: Knoware.no

Post by RalfR »

Tinyfpga wrote:With just 4 lines of code I can write an executable windowing program that does not rely on a huge pile of hidden software for support.
Ok, show the four lines to us!


4E75 7000
Post Reply