4 ms·

One of the nice qualities of man pages is comprehensiveness, while one of the nice qualities of tldr docs is succinctness. Both are mutually exclusive; man pa

One of the nice qualities of man pages is comprehensiveness, while one of the nice qualities of tldr docs is succinctness. Both are mutually exclusive; man pages cannot be both. An examples section in a manpage is a fine idea which I would certainly encourage, but that wouldn't render tldr obsolete.

neckardt 7y ago
Ideally I would like to see an additional section in man pages devoted to examples. The TLDR pages could then be moved into the man pages.
- killjoywashere 7y ago
  tldr didn't choose tar as their front-page demo by accident. The tar manpage is a classic example of the CLI gods apparently going to some effort to design the Examples section to effectively tell new users to bugger the hell off.
  - voltagex_ 7y ago
    https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sektion=0&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt...
    - deleted 7y ago
      [deleted]
  - ori_b 7y ago
    This reads fine to me: https://man.openbsd.org/tar https://man.openbsd.org/tar
  - JdeBP 7y ago
    Only to people who erroneously think that there is such a thing as "the" tar manpage. (-: * https://news.ycombinator.com/item?id=22122279 https://news.ycombinator.com/item?id=22122279
jcl 7y ago
Many man pages have examples, but they consistently bury them at the end, after exhaustively covering every flag, file, or environment variable that could possibly affect execution. It might not be crazy to move the examples section to the top, since it would more quickly provide what most readers are looking for: a sample command line to tweak. Anyone who is genuinely looking for what a particular flag does is just going to search for it anyway, so it doesn't really matter if that flag appears on the 24th screen instead of the 23rd.
- catalogia 7y ago
  Something I like about tldr is that tldr pages are short enough to not necessitate using a pager, so you can print the tldr of a command and read it while typing the command in the same terminal emulator. I know you can disable the pager for man, but the typical manpage is going to be fairly long anyway so the pager is generally desired. I suppose you could pipe man through head to just print out the first section, but honestly tldr seems to fill this niche better than I see that working.
  - jopsen 7y ago
    But they are not system specific... I don't need `tldr opkg` on my system. In fact, having pages I don't need just causes confusion. Moreover, commands can have system specific names.
    - catalogia 7y ago
      My tldr client has a --platform flag that takes 'linux, osx, sunos, or common'. So there is some support there for platform-specific tldr pages at least. Also my tdlr-pages checkout is only 19MB, so I'm not too concerned about bloat. I'm not really sure how having tldr's for irrelevant commands would be a problem, maybe with some shell autocompletions? Maybe there is a way you could prune the tldr-pages checkout? I guess all I can really say is tldr works really well for me and I like it a lot. Nothing is perfect, but tldr is quite nice despite some warts.

neckardt 7y ago

Ideally I would like to see an additional section in man pages devoted to examples. The TLDR pages could then be moved into the man pages.

killjoywashere 7y ago
tldr didn't choose tar as their front-page demo by accident. The tar manpage is a classic example of the CLI gods apparently going to some effort to design the Examples section to effectively tell new users to bugger the hell off.
- voltagex_ 7y ago
  https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sektion=0&manpath=FreeBSD+12.1-RELEASE+and+Ports&arch=default&format=html https://www.freebsd.org/cgi/man.cgi?query=tar&apropos=0&sekt...
  - deleted 7y ago
    [deleted]
- ori_b 7y ago
  This reads fine to me: https://man.openbsd.org/tar https://man.openbsd.org/tar
- JdeBP 7y ago
  Only to people who erroneously think that there is such a thing as "the" tar manpage. (-: * https://news.ycombinator.com/item?id=22122279 https://news.ycombinator.com/item?id=22122279

jcl 7y ago

Many man pages have examples, but they consistently bury them at the end, after exhaustively covering every flag, file, or environment variable that could possibly affect execution. It might not be crazy to move the examples section to the top, since it would more quickly provide what most readers are looking for: a sample command line to tweak. Anyone who is genuinely looking for what a particular flag does is just going to search for it anyway, so it doesn't really matter if that flag appears on the 24th screen instead of the 23rd.

catalogia 7y ago
Something I like about tldr is that tldr pages are short enough to not necessitate using a pager, so you can print the tldr of a command and read it while typing the command in the same terminal emulator. I know you can disable the pager for man, but the typical manpage is going to be fairly long anyway so the pager is generally desired. I suppose you could pipe man through head to just print out the first section, but honestly tldr seems to fill this niche better than I see that working.
- jopsen 7y ago
  But they are not system specific... I don't need `tldr opkg` on my system. In fact, having pages I don't need just causes confusion. Moreover, commands can have system specific names.
  - catalogia 7y ago
    My tldr client has a --platform flag that takes 'linux, osx, sunos, or common'. So there is some support there for platform-specific tldr pages at least. Also my tdlr-pages checkout is only 19MB, so I'm not too concerned about bloat. I'm not really sure how having tldr's for irrelevant commands would be a problem, maybe with some shell autocompletions? Maybe there is a way you could prune the tldr-pages checkout? I guess all I can really say is tldr works really well for me and I like it a lot. Nothing is perfect, but tldr is quite nice despite some warts.