c-blake / cligen

Nim library to infer/generate command-line-interfaces / option / argument parsing; Docs at
https://c-blake.github.io/cligen/
ISC License
496 stars 23 forks source link

Some tiny remarks #205

Closed StefanSalewski closed 2 years ago

StefanSalewski commented 2 years ago

I just added a very brief section about your cligen to the book, see

https://ssalewski.de/nimprogramming.html#_cligen_a_command_line_interface_generator

For writing that section, I read your descriptions at https://github.com/c-blake/cligen. Note, these remarks are based on a plain "nimble install cligen" some days ago, I did not try some form of "@#head" install.

For my example, for the enum help we get (see book section):

select 1 enum Quality

for the rightmost column as default text. Seems a bit strange for me, may a plain "set Quality" be good enough?

For your README

Installing can be as simple as git clone and nim c --path:whereYouClonedTo myProgram.nim.

That remark is a bit confusing, and seems to provide no real benefit. When reading fast, I got the impression nimble install of cligen is not supported.

argument parsing; Docs At

on the top right of the page. I would use a lower case A as "argument parsing; Docs at" ?

And the following link gives an unencrypted page: http://c-blake.github.io/cligen/

And on that page first and last link do not work, give 404 error.

Maybe use https explicitly, or try to enforce encryption when possible. I had to switch to encryption myself recently, as too many people complained or refused reading. Well not really needed for plain content providing pages, but the young kids do not know unencrypted pages at all these days.

is the many examples in my automated test suite:

At the bottom of the readme, seems to be not fully correct grammatically?

Best regards, Stefan Salewski

c-blake commented 2 years ago

I changed the cligen/argcvt.nim auto-help for enums. Those auto-helps are really only placeholders. Anyone even remotely picky/choosy/selective about help messages is expected to add their own help = { "quality": "one of: low, medium, high" }. I would have taken it out of doc comments, too, if that were a convention in Nim code for parameters (like in Java), but it is not.

I would have to punch a new release for this to be nimble-available. I could do that, but I literally just did one yesterday. And maybe you will come up with other ideas. So, I'll give it a few days at least.

I also added nimble as a first, git cone a 2nd idea. { Competent friends have conveyed to me that nimble is undependable (and I personally find it to have various problems). } Since, in my experience, writing a little CLI tool is how many people try out a new prog.lang., and since nimble seems "rough", I try to keep cligen from depending upon anything else, including the package manager and including those install instructions. But I am ok with "dual dependency" as per the new text, and nimble priority as "simpler when it works".

Github recently-ish moved to https only breaking that. I hadn't noticed. Thanks. Fixed along with At -> at.

The grammar at the end of the readme is/was (I think) technically correct but the idea is confusing/complex - a (singular) starting point for (plural) usages is the (singular grammatically of a plural thing) collection of things. I just made it all plural and re-arranged it. Not sure if it's better. { It's also not quite absolutely correct in that there are probably 3 or 4 advanced usages just "tacked on" to existing test programs. }