Adding some style guidelines for help on CLI commands

The question was whether anything existed.

The problem was known, a solution was found, implemented and documented. If it’s not implemented in RISC OS 5, or you want to do it a different way, then that’s a different matter. But a solution exists, and has done for 15 years or so.

A *Help . shows its only ever a few filing system commands which ever used the ~switch convention, everything else used old unix style single dash (abiguously for both single letters and words).

Going with the newer GNU standard (single dash for single letter and multiple combinations, and double dash for words) is far more consistent, and what the vast majority of ported tooling is already using.

Trying to insist on ~switch is not only living in the past, but in a past which didn’t acutally exist!

The question was whether anything existed.

The problem was known, a solution was found, implemented and documented. If it’s not implemented in RISC OS 5, or you want to do it a different way, then that’s a different matter. But a solution exists, and has done for 15 years or so.

Agreed, totally. I’d also emphasise about not re-inventing the wheel.

I also noted that it took you a little digging to find the info in a repository you knew should contain it.
Probably small wonder no one in the RO5 world had read and taken action on it, but they can now…

a solution was found, implemented and documented.

And it looks a good way to resolve the problem. Just a shame that it has been so well hidden for so long! To save effort, avoid re-inventing the wheel, and to ensure compatibility it would seem to me an excellent small piece of design, documentation and code to share.

I can but hope 2021 will be better in all sorts of ways!

I’m pretty sure that the BBC was the first system to offer the extensions to the help interface

Yes, albeit pretty terse.

Going with the newer GNU standard (single dash for single letter and multiple combinations, and double dash for words) is far more consistent,

Optional please. The use of double-dash may be common elsewhere but it isn’t RISC OS and it’s a pain to remember that “this tool does it properly while this tool does it the Linux way”.

where I still use the tools from the 1990s that are of use there are hundreds of commands that use that form.

Name some of them. Because they are all wrong. Page 598 (volume 2 p143) of the RISC OS 2 PRM clearly states (for OS_ReadArgs):

• The command string contains a sequence of commands using the syntax defined by the keyword definition. A command string is made of definitions of the following syntax:
  [-<keyword_name>] <value>

Which implies that even back in the RISC OS 2 days, it was seen as normal and correct to use a minus to introduce options and parameters. Evidenced by the fact that I’ve never come across any command that used a tilde on RISC OS other than the Copy/Count/Delete commands.
Just looked at the Arthur 1.20 binary – it’s the same. Copy/Count/Delete and that’s all.

Furthermore, the only references to the ‘~’ syntax in the current PRM is the documentation of those three commands in FileSwitch, backed up by the code in FileSwitch (…FileSys.s.FSCommands function SetAndGetUtilOption) being the only place that appears to deal with the ‘~’ negation. There’s nothing in the kernel sources that caters for ‘~’ in options.

Also there was never used any dash “-” for options in native RISC OS Software, not in the 1990s, and not out here even in the 2000’s.

Patently ridiculously wrong. BASIC -chain or BASIC -quit ? Been that way since Arthur 0.30.

but in a past which didn’t acutally exist!

Indeed. I’ve just had a look at the Master Welcome manual, and the filesystem is way too simplistic (Copy and Delete, no Count) to take those sorts of options. I’m guessing that this might have been introduced with Arthur’s FileSwitch?

Perhaps we just “think” that it’s something from the BBC MOS because it’s weird and non-standard. I also looked at the SJ MDFS manual in case it is something SJ did… but it doesn’t appear to be.

I guess that the tools I use everyday do not exist

These appear to be tools that you alone have. It has always been common (and is even baked into a command in the OS to aid in parsing parameters) to use the -xxx syntax.

there is usually an unoficial way it is done.

Indeed.

<troll> So please let me be the first to propose that we standardise on the industry standard format of using /h to request help. </troll>

So please let me be the first to propose that we standardise on the industry standard format of using /h to request help.

Now I think you’re being unnecessarily divisive! I also think -h is much too negative, so I propose +h or ++h if you’re feeling double-plus good about what you’re about to do!

so I propose +h or ++h if you’re feeling double-plus good about what you’re about to do!

After 2020 we are obliged to support ~h, with ~ meaning “meh, whatever, I no longer care”.

Oh, wait… hang on… then David wins. 🤦 😂

I will attempt to be more careful about not posting when completely flustered by someones comments. , regardless who.

The general advice is to type it out in a text editor, if you’re wound up then walk away and edit it when you come back.

People tell me that a lot.

telling you that the monitor you use does not exist

It’s not that your monitor doesn’t exist, it’s that either your browser or this site is not behaving entirely correctly and is allowing the content to expand up to sort of fill a FullHD display, but not shrink down enough to be readable on an 800×600 display.
That said, SVGA resolution is seriously old hat so it’s not really a surprise it’s not well supported any more. Heck, the cheap little 7" display I got from Amazon is 1024×600. Info: https://heyrick.eu/blog/index.php?diary=20200807

that one considers there products to be non-existent.

Check your wording and interpretation carefully. I didn’t say non-existent. I said wrong. Not the same thing.

And, on the topic of the monitor (from the other thread):

(you) Try 800 h res or less.

(Druck) No thanks, this is no longer the 1990s.

(you) And that means my one year old monitor does not exist?

Which was not what he was implying. He was suggesting that 800px width was a screen resolution that suits the likes of Windows95… it does exist, but it isn’t something that would be commonplace enough to bother about these days.

Consider the six LCD panels I look at the most:

• My S9 – bought on contract, insane resolution, so we’ll skip over that.
• My PC’s monitor – cost €3 at a boot sale. 21"? VGA 1440×900. Quite a nice screen.
• My Pi’s monitor – cost €5 at a boot sale. 17"? VGA 1280×1024.
• My little LCD panel – cost €30,59 from Amazon. 7" UNIROI HDMI 1024×600 (non-tactile).
• My freebie Android tablet – free with magazine subscription. 10" 1024×600.
• The EeePC901 – bought back circa 2011(ish). 9" (I think?) 1024×600 panel.

I simply wouldn’t look at anything smaller than 1024×600.

The point is, you’re being robbed if you’re paying more than a tenner for a new screen with a resolution of 800×600 or less. Yes, I know people are still selling them, but if you look around you should be able to find a better resolution in the same size factor for about the same price.

But, I understand it can be hard. Prices are all over the place and everybody lies. I’m looking at a monitor with a stand. The desription says it’s a 7" screen for a car, Pi, video surveillance, etc. HDMI + VGA + AV input. 1920×1080 pixels. Not bad for €61,20 (though not Prime so I wouldn’t touch it because non-Amazon returns can be a nightmare). It’s only when digging around in the description that it mentions, almost in passing, that it is a 1024×600 display. Sure, it can probably accept FullHD HDMI input (like my 7" screen can). But that’s not the native screen resolution.

At any rate, you ought to at least be aiming for a 1024×600 at the minimum. And if you can pick up a little HDMI to VGA adaptor (preferably a powered one, not one that leaches off the HDMI’s 5V) than it will open up the ability to pick up a used LCD panel of a normal size. I get them from rummage/yard sales. Because these things are VGA and stuff these days expects HDMI, so they’re no longer wanted.
I’ve got two spares in the shed collecting dust. I think they maybe cost about €15 together, or something?

No need to suffer 800×600!

Though is it not that the guidlines still recommend desktop apps be compatible with 640×480?

I don’t think so. Apps that are expected to be used on low-end smart phones, perhaps.

I’ve just finished making my website responsive to cope with phones and tablets – first time I’ve taken an interest in resolutions below 1280×768. There are a few diagrams that you have to scroll left-and-right as well as up-and-down on lower resolutions, but most pages work okay on small screens now.

I remember pretty recent comments of people asking why the guidlines still call for SW working at 640×480.

You do understand, I hope, that a lot of our documentation is decades out of date?

Additionally, just because a guideline says something doesn’t mean it’ll be implemented. In case you hadn’t noticed, NetSurf handles it’s own copy-paste within itself in a manner akin to Windows.

I’ve just finished making my website responsive to cope with phones and tablets

I’ve handled this in my blog by having the page content be fairly generic HTML, with a php setup that sniffs the browser platform and supplies a different header and footer if it’s a mobile device, and also replaces the images with a proglet that reduces their size and quality so you’ll get a fairly small low res image on mobile (remember, this was originally done when typical mobile data allowances were hundreds of megabytes per month and a lot of places still only had 2G).
The exception is Apple and anything claiming to be a tablet, as generally those are capable of decent rendering and they’re more likely to use WiFi than mobile comms.

It isn’t a case of element hiding, the mobile version doesn’t just hide the right panel with the calendar and links, it simply isn’t provided at all – all to try to reduce data consumption. There’s a “Desktop version” link if you want the full version, and it’s passed back as a parameter ( &keitai=0 ) so it ought to stick.

I’m specifically not using cookies, because, complications.

first time I’ve taken an interest in resolutions below 1280×768

;-) For me it’s not so much the screen size, it’s the page complexity. That’s why it’s a weird mishmash of HTML 3.2 era markup with some CSS bolted on ¹. Back in the early days, working with Fresco was one of the tests I’d give it. Basically, I want it to look more or less correct on an older browser. You’ll notice most modern sites look terrible without the styling as something along the way everybody adopted the idea of using CSS to control how it displays with the markup being just basic markup. That’s good if you know all your readers have a browser capable. I, potentially with people using the likes of Fresco and Oregano, can’t guarantee that.

¹ Don’t complain – a few years back my design changes were tested on NetSurf, Fresco (under emulation), MSIE8, Opera (on Android and XP), Firefox (on Android and XP), Safari (iOS 7), Chrome (Android), and the Android stock browser.
These days I test with NetSurf, Opera (Android), and Firefox (Android) with the latter two in both desktop and mobile mode. I’ve dropped Fresco (can’t remember where I put the SD card with it on), MSIE obviously is dead, iOS7 no longer talks to my site in https (it can’t handle the TLS), and while I look from time to time at how Chrome (Android) renders, I dropped it for both testing and use the moment they introduced that horrible smart text resizing that can’t be turned off. Even so, what I do for my blog would appear to be more thorough than quite a lot of proper important websites. Mom used to complain to me that Amazon’s wishlist was broken in the iPad since about 2017 (as if I could fix it?). And the number of times that Google has refused to let me sign in because my browser is insecure when I’m using Chrome and it’s only a version bump out of date is comical, especially seeing as I had no problem signing in with Firefox 60.0.2…

@ Charles

The standard way to get help on a command is to use *Help.

Thanks, so had a look at Select and found that it seems that what you’re referring to is the addition of a help text file in !Boot.Library.Help where the help file name is the name of the command and the syntax is a tabbed syntax. Is that what you’re referring to?

Obviously commands may offer their own help,

Yup and that’s what we should standardise as well, if it wasn’t clear from my first post then apologies. I guess now it’s very clear that the nature of my question is for external commands only and for their own help, if in doubt please ask :)

but the standard interface to get help on the commands has existed since the BBC (yeah, I’m pretty sure that the BBC was the first system to offer the extensions to the help interface through the service system).

AFAIR yes for the CLI (although the support was basic).

RISC OS GUIDLINES, not some WEB CRAP Guidelines. Desktop Application in RISC OS guidlines. I remember pretty recent comments of people asking why the guidlines still call for SW working at 640×480.

Ah, okay. And when were those RISCOS guidelines written? And when last updated?

I was running an office full of RiscPCs – and before that, A5000s and A540s – in the 1990s. We were using 1600×1200 monitors, but we also had an A4 portable computer. I don’t remember what the resolution of that was, and it only had 16 shades of grey. Admittedly 1600×1200 was cutting edge at that time. But that was a quarter of a century ago.

I have mentioned when talking to others in the area how strange it is that for decades we look for higher and higher resolutions, and now we are looking for the smallest lowest power screen we can find, opisite direction.

Some of you might be. Low power, yes, ideally, but I also consider my eyes, and how effectively I can work.

I guess now it’s very clear that the nature of my question is for external commands only and for their own help, if in doubt please ask :)

Standardisation means the same across the board, so I’d expect the internals to be matching the standard as well.

but the standard interface to get help on the commands has existed since the BBC (yeah, I’m pretty sure that the BBC was the first system to offer the extensions to the help interface through the service system).

AFAIR yes for the CLI (although the support was basic).

Well, the GUI on the Beeb was lacking quite a lot. :)

@ Steve Pampling

Standardisation means the same across the board, so I’d expect the internals to be matching the standard as well.

Sure when this is actually feasible obviously, right? ;)

Just as a note: The C parser I wrote can process also internal parameters same way for module’s commands as for external command tools (details on last post on page 1 of this thread).

Anyway I’d wait for Charles response on my finding on Select, because I ran some tests and my findings doesn’t seems to have found a proper standardisation here:

• First the !Boot.Library.Help directory seems to work only on RISC OS Select from release 4.39 onwards (so probably not even fully standardised across all RISC OS 4.xy up to 6.xy)
• The !Boot.Library.Help appears not supporting internationalisation
• The !Boot.Library.Help seems to create copied output messages out of Help
• It appears to present a possible issue because the help file also contains the command release version and build date, so potential source of misunderstanding if the help file is not updated correctly

So, if that’s the standardised way then we should review it a bit me thinks…

With that said, it does kinda do what people have requested on here which is have the form of:

*Help {external-command-name}

I personally like it, but it appears to need improvements (AFAICT).

Hope this helps understanding my point a bit more.

Well, the GUI on the Beeb was lacking quite a lot. :)

LOL of course! My point was more about other platforms that did present some help messages in their GUIs although if at the time every native help support was pretty basic :D

when this is actually feasible obviously, right?

Yup.