Docs: add the "Topics - Command line interface" section #4044
Conversation
This content already existed and has been largely moved as is. Just the style was adapted to match that of the new documentation, such as link labels, indentation and header styles.
Codecov Report
@@ Coverage Diff @@
## docs-revamp #4044 +/- ##
===============================================
- Coverage 78.45% 78.45% -0.00%
===============================================
Files 461 461
Lines 34077 34077
===============================================
- Hits 26732 26731 -1
- Misses 7345 7346 +1
Continue to review full report at Codecov.
|
| Parameters | ||
| ========== | ||
| Parameters to ``verdi`` commands come in two flavors: |
There was a problem hiding this comment.
This particular description always struck me as a bit odd. Maybe we should at least acknowledge that this is UNIX standard?
| Parameters to ``verdi`` commands come in two flavors: | |
| Like many other command line utilities, ``verdi`` accepts both regular and optional arguments: |
There was a problem hiding this comment.
It is just a collective term to refer to "arguments" and "options" which are POSIX naming conventions. Of course one can also see options as a special case of command line program arguments. I am not sure if your suggestion would help, because it is not the "optionality" that makes an argument an option. It is the way it is specified. An argument is positional and an option is defined through a flag. An argument can be optional just as well.
Before I merge this: what is it that you find odd about the description? The name parameters? Or the fact that it is not clear that this is a POSIX standard and not just something that AiiDA invented?
There was a problem hiding this comment.
Before I merge this: what is it that you find odd about the description? The name parameters? Or the fact that it is not clear that this is a POSIX standard and not just something that AiiDA invented?
The fact that it's not made clear that this is POSIX standard and not something that AiiDA invented. I also find the word flavors very odd in this context.
Since we already being pedantic about naming, as a far as I know, I don't think we are using the POSIX terms correctly.
- The word "parameter" refers to actual values provided as argument.
- The "positional arguments" should actually be referred to as "operands".
- A "flag" is an historical term for an option argument, it does not necessarily refer to the convention of prefixing an argument with one or two hyphens.
https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
https://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html
I'm happy to defer that discussion to a separate issue / PR and just merge this as is.
There was a problem hiding this comment.
I love a good bit of pedantry :) point well taken. I have to admit that the terminology has also been adopted from click. Fine to merge this now and discuss this at a later point.
|
Thanks for the review @csadorf I am putting this on hold because I think it is better to first merge the last remaining scaffolding PR. Also I would like to try to improve the description of parameters if you think it is odd. |
This content already existed and has been largely moved as is. Just the style was adapted to match that of the new documentation, such as link labels, indentation and header styles.
Fixes #4015
This content already existed and has been largely moved as is. Just the
style was adapted to match that of the new documentation, such as link
labels, indentation and header styles.