Wiki: syntax of commands

[annakasprzik]

Maybe for less expert Linux users:
In "Commands" commands are given like this:
annif eval [--limit=MAX] [--threshold=THRESHOLD] [ ...]
but in "Achieving good results" there is an example
annif eval tfidf-en --limit 5 --threshold 0.2 path/to/corpus/validate/
(--limit=n vs. --limit n).
Maybe only use the syntax with '=' and remark that the syntax with blank is equivalent or the other way round?

[osma]

Good catch!

I removed the equals signs from the Commands page. This way the syntax matches what --help gives:

$ annif eval --help
Usage: annif eval [OPTIONS] PROJECT_ID [PATHS]...

  Analyze documents and evaluate the result.

  Compare the results of automated indexing against a gold standard. The
  path may be either a TSV file with short documents or a directory with
  documents in separate files.

Options:
  -v, --verbosity LVL       Either CRITICAL, ERROR, WARNING, INFO or DEBUG
  --limit INTEGER           Maximum number of subjects
  --threshold FLOAT         Minimum score threshold
  -b, --backend-param TEXT  Backend parameters to override
  --help                    Show this message and exit.

[osma]

As an aside, I'm not very happy with the current Commands page. It was originally a spec document for what the commands should be when they were to be implemented... Now it's not 100% up to date w.r.t. the implementation. Maybe it would make sense to either delete it completely, or to generate it from the --help messages like the above? What do you think @annakasprzik ?

[annakasprzik]

You could generate it from the help messages but what helps me a lot are at least some minimal additional comments about an optimal usage of those commands or rather of the functionalities behind them -- much like in "Achieving good results". On the other hand, of course that means that you will still have to update the page by hand. Anyway, I would not delete it completely -- I have referred to that page quite often and I am not always in our virtual machine, so if the page were deleted I would have to log in first in order to take a quick look, that would be less practical.

[osma]

Thanks for your thoughts.

I think it would be best to keep the Commands page, but make it more like a Unix man page. So an overview of the available CLI commands and their parameters, but with some guidance on how best to use them. I think a lot of that guidance should be placed in the --help texts already, whenever possible. The purpose of the page is to document the commands especially for users who don't have a local installation of Annif easily available.

Please note that wiki pages are editable by anyone, so if you see a mistake or an omission and are confident that you know how to fix it, you can just do it without asking.