Adding some style guidelines for help on CLI commands

Hi everyone,
today I am working on some utility/tools I need to create to help me in my coding of other things on RISC OS.

This has triggered some side questions on the fact that, while RISC OS Modules have a fairly well defined standardisation on the matter of providing some form of help on syntax and usage to the user, for external CLI tools there seems nothing being defined (or at least I couldn’t find anything formal).

If there is any standardisation for such matter can someone please pin-point me at it thanks! If not then would it be ok to formalise a similar approach as Linux/BSD have developed through the years?

All thoughts welcome, but please let’s try to stay on topic, pleaseeee :)

For who is not familiar with the Linux/BSD approach here is a simple example:

To request help for a command:

{command-name} {-h}|{—help}

Help general output:

Usage: {command-name} [OPTION]…

{command brief description}

{options list}
{refs}

The -h or -help switch/option format is:

1. Well known in the Unix/Linux world
2. Often appears on external utilities in Windows
3. Matches the existing CLI items like ifconfig

No one should have any issues if you do something for CLI that matches long-standing OS CLI elements

Thanks Steve!

So we want -h and -help (always single dash) instead of (single dash)h and (double dash)help (for the extended form of the option/switch name).

@ DavidS

For RISC OS native things there is a convention, that is clearly outlined in the PRMs as well as repeated just about anywhere that speaks about writing modules (and applies to normal command line applications as well).

Not sure what you mean on that comment…

For modules the help is provided through the help command itself, so syntax is totally different:

help {command-name}

And the output format is very minimalistic because the description is displayed when typing help ModuleName.

so the only thing I can re-use from the help for modules are the symbols used in syntax description.

And finally there is no {ref} section on the original help for modules.

On RISC OS, commands typically work in two ways.

The first, as in the case of many of the built in commands, the parameters are in a fixed order so are just given:

*Copy This That

and if there’s an option string, it goes at the end. It cannot go anywhere else.

The typical response to running the command with no input is:

Syntax: <command name> <options>

For example:

Syntax: a8time <input> [<output>]
Syntax: *Copy <source spec> <destination spec> [<options>]

For more complex things, often taking parameters which aren’t necessarily in any particular order or too many choices to fix which parameter is which, the syntax is like:

*Wotsit -name param1 -othername param2

Often (but not always) parameters can be shortened down to one letter.

People expect at least “-h” to give help.

Examples here are jpegtran, infodump, cc, link and dozens of other things.

would it be ok to formalise a similar approach as Linux/BSD have developed through the years?

Please:

• Don’t treat single and multi letter options as separate things. I know it’s extremely common on Unix to have "-o" (single -) and "--output" (double -), but that’s only perhaps convention because the first person couldn’t write a proper parser. :-)
• Work with native RISC OS names, and not the horribly bastardised filenames that some the GCC stuff seems to want to work with. I don’t recall, but it’s something odd like /SDFS:$/Apps/Something/SomePath but I think the first bit might be wrong.
• Don’t depend upon the presence of an extension in order to tell what the type of a file is. bunzip2 I’m looking at YOU!

I would say that it might be useful to add a single line at the top of the general help output saying what the program is and its version. Refer to cc, link, and objasm for examples.

Just my €0,02 but there are plenty of examples within RISC OS of how command line tools ‘usually’ handle their input.

So we want -h and -help (always single dash) instead of (single dash)h and (double dash)help (for the extended form of the option/switch name).

Check the existing commands, but I can’t recall having to use double-dash on RO (I could have been missing something though)
I think most of the CLI stuff tends to echo the Unix systems the original developers were familiar with and I think double-dash is a more recent, and usually Linux, thing.
Double-dash usually confuses “normal” people – only geeks understand the difference, and everyone ignores us anyway.

Thanks Rick,
ok so no double dash then! :D

I don’t recall, but it’s something odd like /SDFS:$/Apps/Something/SomePath but I think the first bit might be wrong.

no worries, all my code is always native supporting RISC OS file-naming conventions etc, but thanks for the reminder!

That said, most RO users would expect that

*h. Wotsit

was going to reel out the base help for Wotsit and that

*h. Wotsit flavour

would give you help on the flavour of Wotsit. (A little nuance lost on non-Brits)

@ Rick

JFYI ObjAsm accepts double dashes, however it makes no differences between single dash for short form and double for extended form. Just wanted to point this out for correctness.

I can quickly extend my parser to do the same, not a biggie.

Anyway this topics is about deciding together what we would like to have as a standard, so all good feedback so far, thanks a lot everyone! :)

Often (but not always) parameters can be shortened down to one letter.

That should always be the case, as it’s how OS_ReadArgs processes commands. -name and -n are automatically equivalents.

Use OS_ReadArgs to do your parsing, unless there’s a very good reason not to.

Double-dash usually confuses “normal” people

Double-dash is a pragmatic solution to the problem of deciding whether foo -help is a request for help, or whether it wants to set the -h, -e, -l and -p options.

RISC OS doesn’t have that “problem”, because OS_ReadArgs isn’t clever enough to chain options together in this way. However, anything using UnixLib to process its CLI arguments could have the problem, as that uses the same parser that Linux stuff does.

Work with native RISC OS names, and not the horribly bastardised filenames that some the GCC stuff seems to want to work with.

That’s purely to allow things to fall out of the Autobuilder without needing their filename handling code to be changed. If something expects / as a delimiter, it will still work OK on RISC OS by using that icky convention, without the code needing to be patched each time.

@ Steve

That said, most RO users would expect that

*h. Wotsit

Of course, but as I reminded to DavidS, the help {command-name} or h. {command-name} are for internal commands provided by modules. Such help standards are well documented in the PRM and are not part of my question. The problem with external commands is they can’t use the “help” facility offered by RISC OS to modules, hence the need for a standard way to make it easy to get help for external commands.

Also, little side note, the old RISC OS “help” comes from Acorn MOS and so never really had a {ref} (reference section) which could present URLs for more details or updates etc… (and the reasons for this are obvious lol it was defined before the Internet revolution).

When we all agree on the format, someone with forum super-powers could create a page on here with the details to help everyone coding external commands in a way that makes it easy for users to understand how they work.

Makes sense?

OS_ReadArgs. It’s why we put it in there.

@ Steve Fryatt

Thanks

Double-dash is a pragmatic solution to the problem of deciding whether foo -help is a request for help, or whether it wants to set the -h, -e, -l and -p options.

there is also the issue with the [space] characters actually, bash for example splits switches based on the space so, something like:

-o {destination-file}

requires a little help depending on the language used. But again not a problem on RISC OS.

@ everyone

However on RISC OS we have the old Acorn MOS switches, which may need some attention:

copy {source} {destination} ~C F

Do we want to keep them or just leave them to the very very old commands?

The problem with external commands is they can’t use the “help” facility offered by RISC OS to modules, hence the need for a standard way to make it easy to get help for external commands.

How about extending the help system – for “help fred” if the answer isn’t found in a module, try “fred -h” and send the results back to the user?

copy {source} {destination} ~C F

and as i highlighted in another thread today, that’s the same as “copy {source} {destination} ~CF”

@ Alan

thanks for your feedback

How about extending the help system – for “help fred” if the answer isn’t found in a module, try “fred -h” and send the results back to the user?

I am good with that as it would establish a full standard approach across all the various commands. Hopefully no one has an issue with it.

copy {source} {destination} ~C F

and as i highlighted in another thread today, that’s the same as “copy {source} {destination} ~CF”

Yup, so the questions for everyone are:

• Do we want to keep this semantics? (~{flag})
• If so, do we want to keep it identical to the original Acorn MOS? (~C ~G = ~C~G) or should it be always “~C ~G” etc.

if the answer isn’t found in a module, try “fred -h” and send the results back to the user?

+1

Do we want to keep this semantics? (~{flag}

Does anything other than Copy/Count/Wipe use this format?
Taking a look at *Show *Options, it looks like Alarm, Disassemble, and PhotoDesk all use the dash-letter or dash-word style. Perhaps because it gives more flexibility than the older MOS style that can be either on or off but not six.

I’d suggest leaving the ~FLAG~S syntax to Copy/Count/Wipe as a historical anomaly (one of many).

if the answer isn’t found in a module, try “fred -h” and send the results back to the user?

Also +1.

Nothing other than Copy/Count/Wipe should use that format. Historical. Enumerate anything else.

Note that ~CG != ~C ~G

All right,
So, I think we have enough info at this point, unless someone wants to add more.

Next steps:

• If no more info are needed we can collect everything and create a page in the Wiki
• For the changes to the RISC OS help system we should
  • put the request in the Wishlist
  • eventually start looking at the SysComms source in the Kernel section of RISC OS sources (IIRC this is where the Help command is handled)
    • I think in the code section “nohelpfound” probably add a jump to a new section there to handle a file check for the help for an external command.
• I am working out a C template for full implementation so others can just re-use it if they want to.

For the C template that’s what I have got coded and tested so far:

C parser that:

• Uses argv[], char *args (this is for compatibility with modules which do not pass parameters via argv)
• Parser is very easy to use, it requires an “options table” which is create as a struct that holds:
  • parameter token (this to make it possible to use switch statements very easily)
  • long name for each option (for instance “help”), prefix can be both “-” or “- -”
  • short name for each option (for instance “h”), prefix can be only “-”
    • for short names the parser can also handle -xyz (and check for x, y and z as separate options)
  • Help description for each option (for instance “To request for help”)
  • Option flags struct
    • requires_arguments flag: TRUE means it needs a value, FALSE means it doesn’t
    • others for future use
  • Possible pointer to function to automatically call function to handle the option from the parser itself (aka “code-less” call), for instance entry CMD_HELP token may request to automatically call show_help function if needed otherwise set it to NULL

The show_help function is pre-implemented and uses the same struct to display help so the developer only needs to instantiate the struct and populate it with whatever he/she wants (and obviously include the library).

Obviously the C parser compiles fine with DDE latest, needs to test with previous releases.

How’s that sound?

@ Stuart

Note that ~CG != ~C ~G

Thanks for noting it I corrected the example.

My question/statement was more in terms of parsing like “~C ~G” != “~C~G” for the parser because of the absence of the space in between them, but given that we do not want to use the old “~” I think we’re good :)

I remember years ago our school IT guy wanted to know the options for DELTREE in DOS, so he typed it with no parameters expecting it to reply with a usage: type message. He thought it was taking a long time to do so while it thrashed the drive, until it dawned on him what it was doing. He was in the root of the C: drive too.

Could *Help be extended to – if it’s not recognised by a built-in command – either look for a help file to display (either relative to the command, with different path or something else), or to run the command with -help.

MSDOS/Windows is a careful combination of the clever and the stupid. I typed ‘C>format’ and it was intelligent enough to know that c: was a fixed disc so knew it did not have to ask ‘Format drive a: (Y/N??’ and it therefore said ‘press any key to format drive C’. After a little debate with myself whether CTRL-C would abort it, I simply unplugged the computer.

thanks for your feedback guys.

So on the matter of “just run the command without parameters to get the help”. I am not so sure if it’s a safe practice tbh (but I am happy with whatever the majority will want).

The reason I mention this is because there can be (albeit few) commands that do not requires parameters and so in those cases the requirement may collide.

For instance some typical examples (also on other OS):

halt

or

clear

Now while commands like clear aren’t that dangerous, halt will halt the system on a linux box and if executed as root won’t even ask for confirmation.

So maybe the “-h” is probably generally safer.

For what concern the extension of the RISC OS help command please read the last post on the first page of this topic.

Just my 0.5c

This has triggered some side questions on the fact that, while RISC OS Modules have a fairly well defined standardisation on the matter of providing some form of help on syntax and usage to the user, for external CLI tools there seems nothing being defined (or at least I couldn’t find anything formal).

Yes, this had been standardised and in use since about 2004 for command line tools.

At that point you pause and ask yourself “did that happen on both sides of the fence?”

However, if we are trying to establish standard behaviour then rectifying any disparity is usually useful.