I was lucky to first be introduced to man pages by someone who often just called them "manuals" and (to my best recollection) explained them by telling me "Manuals are to be read, top to bottom, contemplated, and maybe read again, before you act."<p>Thus I was never under the delusion that man pages were, or should strive to be, How-To's of some sort.<p>This TLDR tool definitely needs to exist, but in conjunction with man pages, not as a replacement. Manuals should continue to exist in a form that explores and explains the depths of a utility or command in whatever length that might require. I will make adequate use of both.
When people think of manpages, they tend to think of Linux. At least that's what I thought of, until a few months ago when I discovered OpenBSD. Their manual is concise and coherent, unlike the rambling hodgepodge on Linux.<p>Of course it's always nice to have a bunch of curated examples like TLDR or "bro" pages, but just wanted to point out that the manpage situation isn't universally grim.
Hilariously, ITT are lots of comments saying that man is awful, in response to a pot about a "simplified and community-driven" alternative.<p>Breaking news: man pages are community-driven already. You can make them better in your distro of choice. The BSD projects are a little better IMHO at this than Linux because each project has a dedicated team trying to raise the bar and make their docs better than the next distro.<p>So don't make it simplified, don't hail "community-driven", just go and start making suggested changes with the rest of your favourite OS community!
The main thing about man pages is that it is a "manual": reference material for people who already know the basics.<p>If you are just getting started, don't read the man pages, but read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books. Those will generally be tailored to beginners, including features such as discussions of unifying themes between different commands, historical references and more beginner-friendly organization. Beginners don't need to know all the details at first (which are what the man pages provide), but just the big picture.
This is a very interesting project. Years ago when I wanted to learn how to use Linux, my friend who was a system admin at the time just told me to read Man Pages. It was so overwhelming and confusing to say the least, it made me give up on Linux for a long while.<p>Times have changed and I will definitely love to contribute as well as recommend this project.
Man pages feel like RFCs for tools. They have a lot of information about how to use them but they're sometimes pretty difficult to parse. I'm really excited about this project. Whenever I don't know how to use a tool I look at a StackOverflow answer for an example. I've been doing this for as long as I can remember. I'm glad there is a dedicated service for this now.
Lovely.<p>I just wrote a bash client. It uses curl to download the page, pandoc to convert md to html and lynx to display the html page.<p><a href="https://github.com/dilawar/Scripts/blob/master/tldr" rel="nofollow">https://github.com/dilawar/Scripts/blob/master/tldr</a> .
I've always felt like it's a ding on my nerd credentials that I hate man pages. A lot of them feel deliberately opaque.<p>2-3 good examples are what joe blow is looking for when he types "man", and he rarely gets them.
tar makes a lot more sense if you use long options instead of completely cryptic short ones.<p>tar command I've been using recently (scripted of course):<p>To compress:<p><pre><code> tar --create --verbose --use-compress-program="pixz" --file foo.tar.xz --directory <bar_dir> .
</code></pre>
To extract:<p><pre><code> tar --extract --verbose --use-compress-program "pixz -d" --file foo.tar.xz
</code></pre>
Unlike bz2 or xz, pixz it uses all CPU cores both for compression and decompression, and as well allows extracting individual files fast. It's also compatible with xz itself.
I'm not following. The most useful thing on first read (and at other times) of man pages are the examples section. Frequently this section is pretty bare which is unfortunate. We should fix that. Yep with all of that.<p>npm install a thing with multiple clients. Um, huh? Where did that come from? At best now we have 2 competing man page systems, one for the "complete" information and one for the examples section? This is crazy, surely? You're not going to be able to stop using man pages! A replacement that can't be a replacement.<p>But sadly the examples themselves will probably have licensing problems to be able to be incorporated as documentation patches to the man pages - I hope I turn out to be wrong about that.
Thank you, TLDR authors for this tool. It solves a real problem and can coexist with traditional man pages.<p>I may have missed it in the discussion already, but would it be possible for TLDR to favor editable online sources for its content (e.g.: WordPress/Mediawiki with Markdown)? This Wikipedia style of editing may be a big game changer.<p>Caveat: Of course, content would have to be packaged locally for offline use.
If anyone doesn't want to install `npm` and wants to know what client to use, the Haskell/Stack one is nice. It's pretty snappy and has a sane syntax † and data directory (~/.tldr/).<p>† Unlike `tldr.py`, which requires you to do `tldr find <command>` instead of `tldr <command>`
It would be very nice to have some way of integrating this into OhMyZSH as a plugin. OMZ can already do extraction of command line arguments by tab completion (and it will attempt to make a brief description of what the flag does) [0][1].<p>It might be nice to be able to type "tldr compress a folder into a tarball" and click tab to have a set of templates suggested to you. You can navigate to them and click enter to replace your current command line contents with the template.<p>[0] - <a href="https://i.imgur.com/qFnvvaU.png" rel="nofollow">https://i.imgur.com/qFnvvaU.png</a><p>[1] - <a href="https://i.imgur.com/usOwgw2.png" rel="nofollow">https://i.imgur.com/usOwgw2.png</a>
This is a cool idea, but I’ve seen several similar tools and for some reason have never managed to integrate them into my workflow, so I still just google “scp examples” or use my shell history to find previous times when I figured out how to use a command.
So rather than learning a little bit of nroff and making the manual pages better by adding to the EXAMPLES section (or using SmartOS whose manual pages have high quality EXAMPLES sections), it was decided to just re-invent yet another documentation system. I don’t get it: an investment in learning nroff is incredibly valuable, as very high quality typeset documents can be produced with it, so it’s a triple win: better manual pages, no alternative documentation systems and knowledge how to write high quality output in the future. What strange times we live in...
I think man pages should be bound to the code. For example chapter 2 should be part of kernel. When a new system call is added, the associated man page should be in the same commit. If a maintainer see a commit that would have an impact of man page without an update of man page, he can easily refuse the commit.<p>For me the first aims of man pages are to be complete and to be in sync with installed software. The orignal virtue of being terse was to be complete without requiring a lengthy description. If a man page is not complete, it has no excuse for being terse.
On the live demo, it uses a handlebars like template for examples. 'dig {{hostname.com}}'. I think it would be better to have 'dig $HOSTNAME', but maybe that is my bash showing.
Sweet. Added this to my bashrc file.<p><pre><code> tldr() { curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md | less ; }</code></pre>
I find that what helps me the most are the '--help' commands, especially if it has multilevel support, like seen with the docker cli tool.<p>The problem with just providing examples is it doesn't always tell me what each argument does, especially if I have multiple arguments, making it seem like the tool works by having a 'magical' combination of arguments, instead of explaining what each argument does.
they aren't man(ual)s nor are they written in man(7) or mdoc(7), so not really man pages, wish they had gone with roff rather than markdown. tldr ls would be something like this:<p><pre><code> .Dd $MDocDate$
.Dt LS tldr common
.Sh NAME
.Nm ls
.Nd List directory contents.
.Sh EXAMPLES
.Bl -hyphen -offset ds
.It
List files one per line
.Pp
.Nm ls Fl l
.Pp
.It
List all files, including hidden files
.Pp
.Nm ls Fl a
.Pp
.It
Long format list (permissions, ownership, size and modification date) of all files
.Pp
.Nm ls Fl la
.Pp
.It
Long format list with size displayed using human readable units (KB, MB, GB)
.Pp
.Nm ls Fl lh
.Pp
.It
Long format list sorted by size (descending)
.Pp
.Nm ls Fl lS
.Pp
.It
Long format list of all files, sorted by modification date (oldest first)
.Pp
.Nm ls Fl ltr
.El</code></pre>
While reading all the complaints about the man page layout, i find myself thinking that it likely made perfect sense back when teletypes were the predominant terminal.<p>look up something via man, tear off the output, and put it next to you. Maybe collect the most used ones in a binder to bring with next time.<p>Then again, man man may be "enlightening"...
As others have mentioned, the BSD man pages are the gold standard.<p>Man pages should <i>not</i> be "simplified". They should be easy to read, but comprehensive. How comprehensive? I <i>literally</i> learned NetBSD kernel programming by reading man pages. The same with learning how to write X programs two decades ago.
I tried to comment and add my own useful examples to Man pages, but the compression on the files caused some Man pages to break. Maybe this will let me annotate my own Man pages for once.
I don't get the point of this. Man pages already have a "description" section where they give a simplified explanation of the tool, an "examples" section where they give typical usage, etc.