search

c-blake / cligen

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

Feature request: better text wrapping for narrow/wide terminal to improve readability #134

Closed kraptor closed 4 years ago

kraptor commented 4 years ago

When invoking --help-syntax, a big text template is displayed. IMHO this text can be improved dramatically.

Currently is is wrapped with newlines at around col 81, therefore very narrow terminals display too many newlines, hindering readability.

I suggest to: 1) Remove all newlines from the text template and let the terminal wrap automatically (this comes with a drawback: less readability on very wide terminals (see point 2 below). 2) Auto-wrap/clamp when lines longer that 80 chars and if terminal width is over 80 (if possible to get terminal with from envvars, you know.

This way you'll have the best of both worlds: readability on narrow terminals and very wide terminals.

I would apply this to all autogenerated outputs.

kraptor commented 4 years ago

Small question... how to override those templates? Is it possible at all?

c-blake commented 4 years ago

First, for me I always use 80 column terminals and that text does not wrap weird, but some terminals might wrap right at 80. So, maybe 79 chars should be the target.

Second, that entire text is in a single file -- cligen/syntaxHelp.nim. That file gets include d. So, I think with your nim --path set appropriately you can redefine it at will. (You may have to create a local subdir cligen in your project, though.) I'm not saying I'm against improvements, but rather highlighting the "open architecture" of nim/cligen in general.

That said, cligen does call terminalWidth which I got added to the Nim stdlib and use it to auto-wrap in a few places. We might be able to do that here. Auto-formatted text can start to get more ugly. I'd probably prefer to stick to 79 if that works for you.

c-blake commented 4 years ago

In case it wasn't clear, I would, in your project dir, mkdir cligen; cp wherever/cligen/syntaxHelp.nim cligen then edit to your heart's content, then it should be picked up in your local compile. I think "." is always in the path. But if you want to only do it once you might need to have your nim.cfg/config.nims point path to that place ahead of cligen/etc. I recall trying this once years ago and it worked then, though it may have become broken in the meantime.

kraptor commented 4 years ago

Very complete answer. 79 works for me, of course. Narrower terminals are not so common nowadays.

First time I see someone so quicker at answering, thanks :)

c-blake commented 4 years ago

You're welcome. I get that rapid response praise a lot.

That one was easier than the other since it was already set up to be overridden and at least the text I have uses a lot of "indentation" and stuff that I think autowrap might not interact well with. I didn't really explain why my preference for 79 in detail.

c-blake commented 4 years ago

Actually, what terminal do you use? If you are having trouble with this wrapping then you may well have trouble with the terminalWidth-based autowrap in other parts. We might not want to switch off of $TERM because different versions of the very same terminal program may vary in that behavior. We might need to add an environment variable "CLIGEN_WRAP_ADJUST" that you could set to -1 or something.

kraptor commented 4 years ago

Sorry if I don't explain myself so well, just came from other module I was using for option parsing and I'm still getting used to cligen. Minor things really, as now I can compile cleanly with --gc:arc thanks to cligen ;)

c-blake commented 4 years ago

No problem. I'm used to trying to "read between the lines" and glean the right feature hidden beneath some confusion.

kraptor commented 4 years ago

Actually, what terminal do you use? If you are having trouble with this wrapping then you may well have trouble with the terminalWidth-based autowrap in other parts. We might not want to switch off of $TERM because different versions of the very same terminal program may vary in that behavior. We might need to add an environment variable "CLIGEN_WRAP_ADJUST" that you could set to -1 or something.

Hmmm... this may be related to my somewhat complex cmder setup under windows... I have to investigate. In any case, yes $TERM is the way to go, I wouldn't change that.

kraptor commented 4 years ago

Ok, just checked, the cropping happened at exactly col 79, wo you were right about being safe 79 instead of 80.

OTOH, this is what happens on bare-bones cmd narrow console:

imagen

You can see extra newlines... nothing important, though