Tabular compact mode

[eugenesvk]

It seems that even the compact mode isn't compact enough :), but more importantly, I don't like the style of commands as secondary since I'm used to all cli tools showing commands first and description second

I'd like to suggest a tabular compact mode that is also easier to scan since the commands and comments are cleanly separated into columns (and not having to repeat the main command brew helps in increasing the tldr factor ;)):

The first column width should have some max limit, so that very long commands would just "overflow", but due to the support of colors it'd still be easy to visually separate them from the description

↓brew (package manager for macOS and Linux <https://brew.sh>)
 install formula    Install the latest stable version of a formula or cask (use `--devel` for development versions)
 list               List all installed formulae and casks
 upgrade formula    Upgrade an installed formula or cask (if none is given, all installed formulae/casks are upgraded)
 update             Fetch the newest version of Homebrew and of all formulae and casks from the Homebrew source repository
 outdated           Show formulae and casks that have a more recent version available
 search text        Search for available formulae (i.e. packages) and casks (i.e. native packages)
 info formula       Display information about a formula or a cask (version, installation path, dependencies, etc.)
 doctor             Check the local Homebrew installation for potential problems

instead of this

  Package manager for macOS and Linux.
  More information: <https://brew.sh>.
  Install the latest stable version of a formula or cask (use `--devel` for development versions):
      brew install formula
  List all installed formulae and casks:
      brew list
  Upgrade an installed formula or cask (if none is given, all installed formulae/casks are upgraded):
      brew upgrade formula
  Fetch the newest version of Homebrew and of all formulae and casks from the Homebrew source repository:
      brew update
  Show formulae and casks that have a more recent version available:
      brew outdated
  Search for available formulae (i.e. packages) and casks (i.e. native packages):
      brew search text
  Display information about a formula or a cask (version, installation path, dependencies, etc.):
      brew info formula
  Check the local Homebrew installation for potential problems:
      brew doctor

[niklasmohrin]

Thanks for the idea! I like the general look of the output you posted, however there are multiple problems that need to be resolved before we could move forward with development of such an option:

• The output could be very far to the right, if both the command and the description are long; this wraps around in most terminals and destroys the tabular look. We could try to insert line breaks and indent the following line, but that results in a lot of lines if the command spans the majority (or all) of the horizontal space (for example tldr awk). You suggest wrapping and relying on the colors, I am not sure if I agree that that suffices, but I would have to test that in action to judge it
• Not all examples have the page name at the beginning of the example, for example tldr xclip.
• The removal of the leading brew makes sense, because brew has subcommands, but for other commands it doesn't make as much sense. For example, for cat, the first column would be

  
  path/to/file
  path/to/file1 path/to/file2 ... > path/to/output_file
  path/to/file1 path/to/file2 ... >> path/to/output_file
  -u /dev/tty12 > /dev/tty13

• path/to/file -n path/to/file -v -t -e path/to/file

  
  ... and that looks a bit cryptic to me. We definitely don't want to classify pages by whether or not we should display them one way or another. I don't really know what to do about that one.

[eugenesvk]

For example, for cat, the first column would be

Of course it's cryptic, you have not header and no colors, check this simple fix:

[eugenesvk]

this wraps around in most terminals and destroys the tabular look

Nope, and this is using the dumb wrap

With a few tweaks of inserting the newlines like you suggested, you could get

[eugenesvk]

tldr xclip

not in an updated cache, so not sure how big the issue is, but you could also use a special symbol like ◊ in the same color as the man page in the first line to indicate whether the man page is part of the command ↓This assumes the last 3 commands don't have cat

[niklasmohrin]

You clearly arranged these outputs by hand, how would tealdeer find out what the optimal alignment is? Even when composing your examples, you had to make some difficult decisions, like with -v -t -e, I don't see how tealdeer should figure this out without adding tons of code. Also things like aligning the > and >>, but then later down the > is to the left again.

but you could also use a special symbol like ◊

But then we could just put in the command name, for cat I would find that way better than the symbol. For long commands like git commit, it would make it shorter, but the output would be more difficult to read in my opinion.

[eugenesvk]

You clearly arranged these outputs by hand, how would tealdeer find out what the optimal alignment is? Even when composing your examples, you had to make some difficult decisions, like with -v -t -e

It's not difficult: for each column you calculate two numbers:

• maxColumnWidthActual : this allows you to left-space-justify each column and print the next one vertically aligned (except for ↓)
• maxColumnWidthAllowed: (user configurable) this allows you let some very wide cell just overflow

so with the second's column maxColumnWidthAllowed=3 I get this programmatically generated formatted output from three columns of data (reporposing my help shell formatting function for aliases)

Then there are two more things for extra style points (but even without them the ouptut will already be much better structured than currently)

• track the cumulative sum of previous maxX numbers so that if for a given line the 2nd column overflows, but 3rd column is narrow, then the 4th column doesn't need to overflow as you can just cut the justification spaces
• if the line overflows the screen, then start at the next line (but at the same column, not at the beginning of a line)

I don't see how tealdeer should figure this out without adding tons of code

See the algo above, in my shell alias function it's ~60 lines of python code (though the input is already columnar, I guess for tldr you'd have to split the example line)

Also things like aligning the > and >>, but then later down the > is to the left again.

Same thing, if these things represent a column, you get this alignment automatically from the algorithm, every column will be at least space-padded to maxColumnWidthActual, so

• > will become
• > and align nicely with
• >>

But even if it's not aligned (e.g., a command has dozens of variable-parameter pairs and you only want to have a max of 5 columns), it's not worse than what you have currently, so it's not an issue. It'll still be a marked improvement over the current output

But then we could just put in the command name, for cat I would find that way better than the symbol.

Fine, so you'll not have your symbol config variable set and use the full command name. I find the redundancy redundant and will happily eliminate it everywhere with a nice little

⎀

[niklasmohrin]

Since, in contrast to other issues, there hasn't been any reaction to this issue from anyone else, I am going to close. I don't think that this additional output mode is needed currently and it would just add more code for too little users demanding the feature. Additionally, the tldr pages are not written with this format in mind, so I think we would just set ourselves up for lots of future layout issues here. Sorry :/

[eugenesvk]

What contrast? E.g., your first couple of opened issues in this repo opened since 2018/20 have almost reaction from anyone but the repo owners/collaborators, and still open It's just not realistic to expect enough interest to be concentrated in this specific github issue for it to be a meaningful signal, though by closing it you've further reduced the chance of making better design gaining more traction

[niklasmohrin]

There are issues that we initially disagree with but reconsider if there is enough attention (for example #311). There are also old issues that don't have reactions but we still deem useful. If you disagree with these decisions, you can always create and maintain a fork :)

[eugenesvk]

You failed to address the point: how would you reconsider with enough attention if you've significantly decreased the chance of getting attention by closing the issue?

[niklasmohrin]

I am afraid I won't. The issue has been open for eight months, now I finally rejected it as I do not see it belonging to either of the two categories of my previous comment.

Please check your tone going forward, this is an open source project that @dbrgn and I maintain in our free time for no compensation. You have repeatedly come to my attention for not accepting decisions we make regarding the project and communicating as if a) we are some kind of service that you are a paying customer of and b) your opinion is the ultimate truth. If you are unable to communicate appropriately, we will have to block you from participating in the tealdeer project discussions.

[eugenesvk]

You can't fit it in those two categories for the reason I've mentioned

this is an open source project that @dbrgn and I maintain in our free time for no compensation

And this is an open source comment with valuable design feedback that I've provided in my free time for no compensation

Also, I accept your decisions, I just point out the flaws in your arguments supporting those decisions

Unfortunately, your tone perception is just as astute - what paying customer would not make any demands to impement a feature?