Opened 8 years ago

Last modified 7 years ago

#120 new enhancement

Improve built-in help system

Reported by: Ian Hinder Owned by: mthomas
Priority: major Milestone:
Component: SimFactory Version:
Keywords: Cc:


SimFactory currently provides a single help screen when you type "sim help". I would like to be able to do "sim help <command>" and get help which is relevant for that command. This help should say briefly what the command does, and give a comprehensive list of the options specific to that command. The top-level "sim help" command should then give a list of the commands, and a list of the simfactory options which apply to all commands. This first help page should be kept as brief as possible so that it is easy to see at a glance what commands are available. The most common commands should be listed first, and maybe separated from the less common commands.

I think this is important as it is the first port-of-call when someone wants to know how to use a particular feature, especially when the syntax is similar but not quite the same as in SimFactory 1.

Attachments (0)

Change History (8)

comment:1 Changed 7 years ago by Roland Haas

Has there been any progress on this? Anything would be of help, really :-). I just spend half an hour trying to understand why simfactory does not like

simfactory/bin/sim create vertex --walltime 24:00:00 --parfile par/qc0-mclachlan.par --procs 192 --num_threads 1

I was almost ready to read the source code until I found Ian's report of a user guide in ticket #502 (the user guide is very helpful by the way. Could it be linked to on the simfactory website, please?).

comment:2 Changed 7 years ago by Erik Schnetter

As an aside: the historic reason for this is that I like Lisp and Scheme, and whenever I can get away with it, I use hyphens instead of underscores.

As another aside, either --procs should become --num-procs, or --num-threads should become --threads.

comment:3 Changed 7 years ago by Roland Haas

So it was the hyphens? I had thought that I simply cannot pass anything other than --parfile to create? Sigh. I just realise that it actually did tell me "error: no such option: --num_threads". Oh well. The help text says "--procs=<int> Processors to use". Is this wrong?

comment:4 Changed 7 years ago by Erik Schnetter

The help text for "--procs" should be "number of cores to use", since "processors" has come to mean something slightly different (a hardware abstraction that has no direct meaning for software). So maybe the option should be "--cores" instead...

The help text for "--num-threads" should be "number of threads per process".

Yes, I believe the underscore is your error.

comment:5 Changed 7 years ago by Roland Haas

Thank you. It seems to work now. I vigorously support renaming --procs into --cores, given that I have in the past missread --procs to mean (MPI-)processes, which does not really work.

comment:6 Changed 7 years ago by Erik Schnetter

Does this vigor extend to creating a patch (for --cores and --threads), keeping --procs and --num-threads to remain compatible, optionally with a usage warning?

comment:7 Changed 7 years ago by Roland Haas

Well now that I said it I guess I will have to put my money where my mouth is. I'll code up --cores and --threads as synonyms to --procs and --num-threads respectively allowing only one to be specified. I'll have to see how to interface with Ian's documentation system. Not today though.

comment:8 Changed 7 years ago by Ian Hinder

@Erik: The use of a hyphen to separate words in 'long-style' options is very standard nowadays (see e.g., so it's definitely what people should be expecting, irrespective of Lisp and Scheme :)

The underlying problem here is reported in #221. SimFactory should not just ignore unrecognised arguments; the fact that it does means that if you mis-type an argument, you don't get a useful error message. This is quite a serious user-interface problem, and now that SimFactory 2 is the default in the ET, I think this should have a higher priority.

Regarding terminology, Erik very helpfully provided ( an explanation of all the terms such as cores, procs, threads, N this per that etc, and the different things they mean in different contexts. It would be really helpful if this could all be sorted out and made consistent throughout SimFactory. I doubt that anyone other than Erik truly understands the current system, so I don't think it will be too much of a problem to change the interface in trunk if we can make it fully consistent.

@Roland: There are ini files in the SimFactory source repository which describe all the options, their defaults, and their help text, and the user guide is regenerated automatically when there is a commit. There isn't a way to mark two options as synonyms in SimFactory's documentation system, as far as I know, so you could just put the information there twice and say "Deprecated: Synonym for XXX".

I will add the pointer to the user guide to the SimFactory web page.

Modify Ticket

Change Properties
Set your email in Preferences
as new The owner will remain mthomas.
Next status will be 'review'.
as The resolution will be set.
to The owner will be changed from mthomas to the specified user.
Next status will be 'confirmed'.
The owner will be changed from mthomas to anonymous.

Add Comment

E-mail address and name can be saved in the Preferences.

Note: See TracTickets for help on using tickets.