Improve built-in help system

Issue #120 new
Ian Hinder created an issue

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.

Keyword:

Comments (8)

  1. Roland Haas
    • removed comment

    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?).

  2. Erik Schnetter
    • removed comment

    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.

  3. Roland Haas
    • removed comment

    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?

  4. Erik Schnetter
    • removed comment

    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.

  5. Roland Haas
    • removed comment

    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.

  6. Erik Schnetter
    • removed comment

    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?

  7. Roland Haas
    • removed comment

    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.

  8. Ian Hinder reporter
    • removed comment

    @Erik: The use of a hyphen to separate words in 'long-style' options is very standard nowadays (see e.g. http://www.gnu.org/software/libc/manual/html_node/Argument-Syntax.html), 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 (http://damiana2.aei.mpg.de/~ianhin/simfactoryuserguide/processterminology.html) 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.

  9. Log in to comment