Proposal: additional examples (more than 8)

[fazlearefin]

I am just throwing an idea here. Currently, the number of examples for any command is limited to 8. Not all commands are the same. Showcasing the most common uses for commands such as curl or nmap is very difficult using 8 examples only; and there are many such commands. So I propose having additional example pages. They can be structured in a directory structure which can be ignored by existing clients. New clients which will be aware of this new pages can show additional examples through a switch (like tldr --show-extras).

The point I am trying to make is to provide more example uses for a command, should the command warrant so. It can be done using additional pages or by other means.

Feel free to share your thoughts.

[sebastiaanspeck]

A good idea, I personally think that a maximum of 8 examples can be treated as a warning instead of a blocking issue in a PR

[spageektti]

I think we could create additional pages with extra commands or something, but I also think that the main page still should be limited to 8 examples.

[fazlearefin]

I have been contemplating about this. Having additional pages does carry overhead like making sure examples are not duplicated in the additional pages or vice-verse.

The other option could, like @sebastiaanspeck said, have a soft limit for tldr pages. There should be a hard limit as well, like 64, for example. That way, all examples for a command can exist on a single page. The clients can be modified to show the first 8 examples by default, and if --show-extras is passed to tldr, it will show all examples.

I have tested with the official python, rust, and node clients. They have no problems displaying pages with more than 8 examples even in their current versions. So this makes sure even if the client is not updated, pages with more than 8 examples will not break anything.

[spageektti]

That way, all examples for a command can exist on a single page. The clients can be modified to show the first 8 examples by default, and if --show-extras is passed to tldr, it will show all examples.

It would be fine this way, but only if the most popular clients are updated.

The maximum limit should not be too high, as this would go against the idea of tldr-pages.

[kbdharun]

Hi, Will go through the conversation soon, linking this existing discussion for reference -> #2799.

Also, pinging some maintainers from the previous conversation @sbrl @waldyrious to hear their new viewpoints.

[waldyrious]

Thanks for digging up the previous discussion, and for the ping, @kbdharun! Other very relevant discussions are in #686, which initially proposed limiting raw line count rather than number of examples, and in #1149, where the hard limit of 8 originally was decided (and afterwards encoded in the contribution guidelines in f0d4c16).

So, here's an bit of historical context that illustrates my stance on this: back when tldr-pages was created, in 2013, I had been involved with technical contributions in the Wikimedia ecosystem, and as part of that I helped maintain a page in the mediawiki.org documentation wiki, which was called, coincidentally enough, Git/TLDR. In particular, I was following recommendations from the original creator of that page, to keep its contents short enough that they would roughly fit on a single printed page of paper. This arbitrary requirement helped people contributing to that page ensure it didn't become larger and larger over time, and focused on the real tl;dr aspects of the topic. So when I came across tldr-pages, and noticed that the CONTRIBUTING.md file already recommended a similar limit (5/6 examples), it was pretty natural for me, and I embraced this objective metric as a helper and reminder to implement the much harder subjective task of making (and keeping) the pages approachable and readable.

Reading back the discussions, I am inclined to reconsider the argument of limiting the number of lines (or, more concretely, default terminal sizes), as that can ground the length guidelines on a less arbitrary criterion, similar to the "one printed page" from the above. In particular, and as pointed out in #686, many terminals have a default starting size of 80×24 (24 lines of 80 characters each, originating from early interfaces like the venerable VT100 terminal). Especially for new users of the command line, it would be important to have the output of a tldr some-command invocation fit within the default terminal window size. It gets even worse if we consider that we put the most important commands at the top, and these are precisely the ones that scroll off the window if the output is larger than the terminal window. (Besides, there are other good reasons to keep file contents within small limits.)

Now, as we know, the contents of pages can be rendered in a myriad ways depending on the client, but IMHO we should at least make it possible to fit one tldr-page entry in the default terminal size. This can mean clients whose default rendering style skips blank lines (relying on formatting to make the content readable), like tinytldr; or clients that have an option to customize the output to be printed in a compact mode, like multi-tldr.

Speculative proposal that entails a page format change

In fact, we could even consider making the source file itself compact, while respecting the markdown format, so that even a mere cat path/to/tldr-page.md would fit within a 24-line terminal window (clients could then do the opposite transformation, and introduce whitespace for readability). I know this last option resurfaces the dreaded #958, but I think it's worth considering while we're on the topic. We would be looking at something like this:

# command name

> Short, snappy command description.
> Preferably one line; two are acceptable if necessary.
> More information: <https://example.com/command_name/help/page>.
> See also: [[foo]], [[bar]].

- Example usage 1:
  `command_name options`
- Example usage 2:
  `command_name options`
- Example usage 3:
  `command_name options`
- Example usage 4:
  `command_name options`
- Example usage 5:
  `command_name options`
- Example usage 6:
  `command_name options`
- Example usage 7:
  `command_name options`
- Example usage 8:
  `command_name options`

... which IMO is pretty readable as-is, and results in the following:

command name Short, snappy command description. Preferably one line; two are acceptable if necessary. More information: https://example.com/command_name/help/page. See also: [[foo]], [[bar]]. Example usage 1: command_name options Example usage 2: command_name options Example usage 3: command_name options Example usage 4: command_name options Example usage 5: command_name options Example usage 6: command_name options Example usage 7: command_name options Example usage 8: command_name options

(Note that this already includes a two-line description and even a line for a possible "See also" line — see #784)

All that said, as can be seen in the code snippet in the above collapsed content, even the most compact content presentation would at most net us one extra example (from 8 to 9) if we adopt this 24-line terminal limit — so in effect we would still be in pretty much the same situation as we are now, with the the problem described at the start of this issue. (The only benefit would be a less arbitrary justification for the 8 examples.)

I am definitely sympathetic to the need to include additional examples for commands that are particularly challenging to describe, so I am inclined to support an option like --extended to display content beyond the limits described above (I agree that if we add it, it should be in the same file). Just to make it clear: such an option would need to be opt-in, so that the default experience would continue to be displaying the shortened form of the page. (For illustration purposes: if we were to adopt the compact markdown source files I described above, this behavior would be equivalent to cat path/to/tldr-page.md | head -n 24).

Looking forward to read your thoughts!

[fazlearefin]

Thanks for going into details about the history of tldr-pages, @waldyrious . I had no idea about some of the things you mentioned.

Regarding your argument about 80*24 char default terminals, our tldr pages are already violating the 80x24 limit restrictions for scroll-free viewing, even for the most common commands such as ls, cp, mv.

The solution to tldr pages obscuring most common examples at the top can be solved by providing pager like functionality (think less) within the tldr client.

[waldyrious]

Regarding your argument about 80*24 char default terminals, our tldr pages are already violating the 80x24 limit restrictions for scroll-free viewing, even for the most common commands such as ls, cp, mv.

Well, that wouldn't be the case if we switch to a more compact format I proposed in the "speculative" section of my previous comment :) for example, ls would become this:

# ls

> List directory contents.
> More information: <https://www.gnu.org/software/coreutils/ls>.

- List files one per line:
  `ls -1`
- List all files, including hidden files:
  `ls -a`
- List all files, with trailing `/` added to directory names:
  `ls -F`
- Long format list (permissions, ownership, size, and modification date) of all files:
  `ls -la`
- Long format list with size displayed using human-readable units (KiB, MiB, GiB):
  `ls -lh`
- Long format list sorted by size (descending) recursively:
  `ls -lSR`
- Long format list of all files, sorted by modification date (oldest first):
  `ls -ltr`
- Only list directories:
  `ls -d */`

...which only takes up 21 lines (so there would even be room for one additional example!)

That said, and as I conceded before, this approach would pretty much keep us with the current limit of examples per page, so it doesn't really address the crux of this issue.

Your proposal to implement a pager functionality sounds pretty interesting, actually. I would definitely support an UX similar to what git commands implement, i.e. printing the entire output if there's available space in the terminal, and falling back to a pager if there isn't. That's an even better approach than the --extended option since users wouldn't need to explicitly pass an option to tldr to get the extra content when the room for it is there. It would even ensure we fit smaller terminal windows (even smaller than 24 lines)!

Given the availability of the LINES and COLUMNS environment variables, this sounds pretty doable. If sufficient clients implement this, I would be OK with increasing the page limit.