Hacker News Reader

Comment by topspin | Hacker News Reader

> The maintainers would be thrilled to have them.

Would they?

The tldr.sh site prominently offers a sample of usage examples for a command; tar specifically. If one checks the tar man page there are no examples. This is policy, apparently promulgated by GNU et al. in favor of "info". I haven't the time right now to hunt down the official position, but here[1] is a SO discussion.

Should this TLDR thing correct that long standing mistake I'm all for it. Also, info is one of the most hostile TUI programs I've ever encountered and I resent using it.

[1] https://unix.stackexchange.com/questions/306189/why-dont-man...

View on HN

> If one checks the tar man page there are no examples.

* https://www.freebsd.org/cgi/man.cgi?query=tar#EXAMPLES

* https://man.openbsd.org/tar#EXAMPLES

* https://illumos.org/man/1/tar#examples

* https://www.ibm.com/support/knowledgecenter/ssw_aix_72/t_com...

* http://osr507doc.sco.com/cgi-bin/man?mansearchword=/usr/man2...

You are clearly very limited in your user manuals. (-:

I certainly should have qualified with "GNU tar". This raises the question; does TLDR exist simply because of GNU's dysfunction? Would TLDR exist if one could simply 'man tar' on a GNU tar system and pop down to the Examples section as one apparently can in just about every other *nix?

(and one currently can't, given the unmodified man page from the most recent 1.32 release)

I'm aware of GBU's preference for info but systems vary. Just to use your example, I'm typing this on Slackware and when I pull up man tar there are three examples, right after Synopsis and Description. Examples for extracting, both gzipped and regular archives, and creating a tar file are given.

And when I shell into an OpenBSD server their man page for tar has several examples at the bottom of the page.

Man, IMO, is a lot like Linux distros in that they are not all created equal, pull from a lot of different sources and can be inconsistent if you're not looking at the correct ones for whatever system you are on.

I too think TLDR is a good idea but that's no reason not to encourage that some of their work be ported back to man pages in their examples' sections.

A quick survey of GNU tar man pages, by program version and the date that appears in the page itself:

   1.23 March, 2012:    no examples (RHEL 6)
   1.26 March, 2015:    no examples (OpenSUSE 13.1)
   1.26 February, 2016: no examples (CentOS 7)
   1.29 March, 2016:    limited examples (Ubuntu 1804)

The last has no actual "EXAMPLES" section in the man page; only some incidental examples appearing among a discussion of "Option styles." I suspect this is also what you see; it's in the same position in the page. So there is some evidence that examples aren't entirely prohibited in GNU man pages, at least in recent years. Progress, I guess. The latest work on this man page (release 1.32) shows no further progress.

TLDR goes well beyond those incidental examples and is far closer to what I'd hope to see; first class, worked example forms eagerly supplied. Without suffering info.

Fair enough and as mentioned this was Slackware and the maintainer, Patrick, is known to have a fondness for BSD so maybe his influence can be seen here.

For what it's worth the Slackware page does have an Examples section so it's not exactly what your seeing on Ubuntu but the examples themselves may be the same. As mentioned there are only three but they are probably the three examples needed most by 95% of users.

And, since I wasn't clear in my previous post, I absolutely agree about info. It may have been a nice thought when hypertext based systems were young and new things needed to be tried but it should have quietly died by now IMHO.

Reply on news.ycombinator.com