torus-cli
torus-cli copied to clipboard
manifoldco
Style guide - White space and layout
Placeholder for discussion about these facets of the style guide.
Talking points
- Newlines after command input
- Tabwriter spacing
- General newline usage
- Table column spacing
My opinion:
- No newline after command
- Newline after primary output, then final message (ie. success/failure)
- Tabwriter/table spacing should be 8
Something I just thought about: Everything should word wrap!
We can easily determine the window size on execution, and wrap text accordingly. This means that all the other elements (tables, lists, errors etc) should obey this too.
Word wrap, yes!
@jeffandersen
No newline after command
This one is pretty inconsistent in our current version, agreed it should be no newline.
The question that I know @jbowes will have strong opinion on is whether you do newline after all the output. A lot of product CLIs do this, but very few system utilities do.
$ torus cmd
This is our output
$ my next command
versus
$ torus cmd
This is our output
$ my next command
I prefer the latter, new line after output. But that's just because I like whitespace and it distinguishes nicely between the last command.
I'm against vertical whitespace immediately following entering the command, and after the output of the command:
- its not common (but not important enough to break the mold for), so its off-putting
- if someone likes whitespace before their prompt, they can set their prompt to include it
whitespace is perfectly fine within the body of the output to delimit things.
Tabwriter/table spacing should be 8
on an 80 column width terminal, that's quite a lot. how about 4 instead?
if there's more horizontal space than is required, should we increase that width to try and fill the screen?
We can easily determine the window size on execution, and wrap text accordingly. This means that all the other elements (tables, lists, errors etc) should obey this too.
when wrapping, or in general, should we leave some whitespace at the edge of the screen? I'm partial to leaving 1 or 2 chars.
Something that's tricky with wrapping the cells in tables is how do you decide which cell to wrap, and how much? I guess we build a new layout engine ;)
on an 80 column width terminal, that's quite a lot. how about 4 instead?
sure I was just drawing on what seemed to be used now, but we can reduce it.
I guess we build a new layout engine ;)
Yeah i was thinking about that when writing that bit. It's tricky, but sometimes you just know that a particular column contains bulky output and would be smart to wrap... but then you get into how to implement that sanely.. for which a new layout engine might be needed.
I'm against vertical whitespace immediately following...
@jbowes I'll defer to you and standard formatting on this one. We should adhere to the standards for this kind of stuff as much as possible.