Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

TLDR pages: Simplified, community-driven man pages

tldr.sh

Post reply on HN
Print view View original

101–110 of 179 posts

Re: TLDR pages: Simplified, community-driven man pages

#101

Post by mongol »

ddevault wrote: post #27

A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.

It would be interesting to take a step back and consider what man pages actually are. Are they documentation structured in a specific way, dating back to Unix origins, or are they what the user sees if they type "man command" on the command line? Because if we consider the latter, I think it will be much easier to see radical improvement of the "man experience"

If I type "man ps" I see

    Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this)
     * ps (1)
       ps (1p)
    Man: What manual page do you want?
What if I instead saw

    Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this)
     * ps (1)
       ps (1.tldr)
       ps (1p)
    Man: What manual page do you want?
where the man command retrieved that information from the TLDR-pages site?

In the last years we have seen many innovative Rust re-implementations of classical commands such as cat, find, grep. Maybe the man command is next up?

Re: TLDR pages: Simplified, community-driven man pages

#102

Post by dylanz »

ddevault wrote: post #27

A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.

+1 ... we should be working on improving "the actual" man pages. There is an "Examples" section in OpenBSD man pages that help out quite a bit. I'd rather have one definitive place for man pages (rather than many), and I'd rather have them be accessible from the OS (and not require an internet connection).

Re: TLDR pages: Simplified, community-driven man pages

#103

Post by kbenson »

edw wrote: post #59
spenczar5 wrote: post #46

Earlier quoted context omitted.

Do you have examples of that refusal? I'm unfamiliar.

Based on my experience, the problem may be that man pages are often not where one learns how to use a tool. I still remember from long, long ago when I told a greybeard that I was trying to learn sed by reading the man page. He replied, "God help you," and guffawed. While some man pages have examples, I don't know if man page writers see their job as teaching readers how to use a utility. The goal of man pages more o…

The more complex a tool, the less likely a man page is going to be a good way to distill and impart the information of how to use it. Bash's mane page is so large I can almost never find what I'm looking for.

At the same time, that means a TL;DR type page is also likely to be useless. For the vast majority of software run from a shell, a man page is sufficient, and examples can be (and often are) added to good effect.

I will note that some projects split very large man pages into sub-pages, and that can work well. For example, ip, and much of the man pages on BSDs that explain how different technologies are implemented (for example, follow the references in the man page for ifconfig on OpenBSD).

Re: TLDR pages: Simplified, community-driven man pages

#104

Post by b5n »

thrwaway69 wrote: post #61
CaptArmchair wrote: post #26

Earlier quoted context omitted.

> it's pretty clear from the context I think that largely depends on who's using the tools and how acquainted they are with command line tools. An absolute beginner likely will not know what tar's 'f' flag does, or assume something else. > OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :) And I absolutely have no…

I will bite - I have been using linux for 4 years. I have used tar a lot and I don't know what v means. I switch between -xvf, -xvz, etc. x - extract | f - file | z - operating on tar.gz or similar. Edit: v - verbose

man tar | awk -F , '/-v,/ {print $2}'

Re: TLDR pages: Simplified, community-driven man pages

#105

Post by smhenderson »

topspin wrote: post #95
smhenderson wrote: post #90

Earlier quoted context omitted.

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, i…

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…

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.

Re: TLDR pages: Simplified, community-driven man pages

#106

Post by beefhash »

joshklein wrote: post #83
diebeforei485 wrote: post #80

Earlier quoted context omitted.

No, they serve two different purposes. Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept. This is something different. It's a tutorial of how to do the most common things using that tool. It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples? Unless you've read formal specs for ot…

> they serve two different purposes I agree, but I'm also painfully aware of man page incompleteness every time I'm on a non-OpenBSD system. I'd be grateful to anyone who chipped away at proper tagging for any GNU software. One should be able to :t to jump to the reference for any flag.

That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor and don't use mandoc (which is... exactly only AIX and HP-UX at this point), so they write all their text in man so that they render correctly everywhere.

For tagging, the formatting would need to be redone to be mdoc, which breaks both the OSes mentioned above and would be an immensely arduous task at this point. Probably not going to happen.

Note GNU and and the Linux man-pages project are mostly outliers; everyone else that lives in BSD/illumos land has long since moved on to mdoc since like the 80s. See also https://www.usenix.org/system/files/login/articles/141-dzons...

Re: TLDR pages: Simplified, community-driven man pages

#107

Post by b5n »

Brave-Steak wrote: post #78
upofadown wrote: post #49

This tends to be more of an issue with GNU programs that have info pages. You are not really supposed to use the man pages in that case. The info pages for GNU tar have lots of examples scattered throughout: * http://www.gnu.org/software/tar/manual/ BSD systems, for example, have much better man pages that have an actual "EXAMPLES" section near the bottom.

The thing is - I don't want to go to some website or pour through pages and pages of documentation when I want to do one specific thing. I want to do something and move on with my life. My job isn't learning every command line switch under the job.

It's just text - so all the text formatting/search/manipulation commands are available to you. Manpages are really easy to use and navigate, given you use them how they're meant to be used.

man man | grep -A 10 EXAMPLES

man tar | awk -F , '/-v,/ {print $2}'

Re: TLDR pages: Simplified, community-driven man pages

#108

Post by Brave-Steak »

b5n wrote: post #107
Brave-Steak wrote: post #78

Earlier quoted context omitted.

The thing is - I don't want to go to some website or pour through pages and pages of documentation when I want to do one specific thing. I want to do something and move on with my life. My job isn't learning every command line switch under the job.

It's just text - so all the text formatting/search/manipulation commands are available to you. Manpages are really easy to use and navigate, given you use them how they're meant to be used. man man | grep -A 10 EXAMPLES man tar | awk -F , '/-v,/ {print $2}'

Or I type ‘tldr’ and don’t waste my time? I swear to god, engineers are so focused on efficiency and yet are so eager to waste so much time and effort on repeating crap like this unnecessarily. Just think about the context switches alone necessary to type all that.

Re: TLDR pages: Simplified, community-driven man pages

#110

Post by b5n »

Brave-Steak wrote: post #108
b5n wrote: post #107

Earlier quoted context omitted.

It's just text - so all the text formatting/search/manipulation commands are available to you. Manpages are really easy to use and navigate, given you use them how they're meant to be used. man man | grep -A 10 EXAMPLES man tar | awk -F , '/-v,/ {print $2}'

Or I type ‘tldr’ and don’t waste my time? I swear to god, engineers are so focused on efficiency and yet are so eager to waste so much time and effort on repeating crap like this unnecessarily. Just think about the context switches alone necessary to type all that.

It was easy for me, no context switching. I assume basic use of grep and awk shouldn't be too much of a stretch for most Linux savvy engineers.

I'm happy TLDR fits your needs. I was just demonstrating how I use manpages effectively in hopes it might assist you.

Post reply on HN