13 ms·

Simplified and community-driven man pages

369 points by akras14 9y ago

shmerl 9y ago
tar makes a lot more sense if you use long options instead of completely cryptic short ones. tar command I've been using recently (scripted of course): To compress: tar --create --verbose --use-compress-program="pixz" --file foo.tar.xz --directory <bar_dir> . To extract: tar --extract --verbose --use-compress-program "pixz -d" --file foo.tar.xz 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.
- gboudrias 9y ago
  By the way, at least for the ones I've tried, --extract now figures out the compression algorithm, so --use-compress-program is possibly redundant. With the cryptic short options it's only one letter, but I find it makes it easier to remember a distinct "4-letter scrabble" for creation versus a "3 letter scrabble" for extraction. (For the long options you save a lot of typing!)
  - shmerl 9y ago
    tar wouldn't be able to figure out to use pixz instead of xz in this case just using implicit deduction. I don't really type those options, but use some simple wrapper scripts :) Something like pixzcompress / pixzextract. Scripts also take care to differentiate between directory and a single file.
    - imiric 9y ago
      If you're OK with wrapper scripts, take a look at dtrx[0]. It can extract many different formats, so assuming you have the tools already installed, extracting anything can be done with `dtrx <filename>`. [0]: https://brettcsmith.org/2007/dtrx/ https://brettcsmith.org/2007/dtrx/
      - shmerl 9y ago
        Interesting, but pixz is too new for it, plus it looks like it's using extension to determine the type, so it won't work for the same reason as above. The benefit of pixz is much faster compression / decompression.
      - digi_owl 9y ago
        There is also atool. http://www.nongnu.org/atool/ http://www.nongnu.org/atool/
    - gboudrias 9y ago
      Good to know, thanks! :)
  - deleted 9y ago
    [deleted]
Xunxi 9y ago
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. Times have changed and I will definitely love to contribute as well as recommend this project.
- paulie_a 9y ago
  I've been using Linux for twenty years and have maybe spent two hours reading man pages. Man pages seem to be written by engineers that honestly wrote them like it was code. It's dense material and assumes you can decipher it. Since the days of Alta Vista and webcrawler. And even with Google, I skip the first link (man pages) and find a better explanation
- IgorPartola 9y ago
  Heh. Should have told you to go read the FreeBSD manual. That’s the first OS that made sense to me because of it. I actually ended up translating parts of it to Russian because I enjoyed it so much. NetBSD was the first thing I got running reliably on my ancient hardware. Linux eventually worked but it was process. And man pages don’t explain what the system does at all.
  - JdeBP 9y ago
    Of course, as people have pointed out already, a user manual is not a tutorial, and the two are distinct and complementary. This is something that one finds in many spheres, from Microsoft operating systems to Linux ones. One of the things that MSDN and TechNet doco does is have both "X reference" and "using X" sections. Manual pages are reference doco, in this way of organizing things. The BSD worlds put the "using X" doco into what are often called "handbooks" or "guides". * NetBSD Guide: https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html https://freebsd.org/doc/handbook/book.html * DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/ https://www.dragonflybsd.org/docs/handbook/ * TrueOS User Guide: https://www.trueos.org/handbook/trueos.html https://www.trueos.org/handbook/trueos.html * PC-BSD User Guide: http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/) Some parts of the Linux world do the same. upstart had the Upstart Cookbook for example: * http://upstart.ubuntu.com/cookbook/ http://upstart.ubuntu.com/cookbook/ My nosh toolset comes with user manual pages for the individual commands, written in DocBook XML as I just mentioned in https://news.ycombinator.com/item?id=15779321 https://news.ycombinator.com/item?id=15779321 , and a nosh Guide. * http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html * http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-socket.html http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-soc... * http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatsheet.html http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatshe... * http://jdebp.eu./Softwares/nosh/guide.html http://jdebp.eu./Softwares/nosh/guide.html The Linux Documentation Project was supposed to contain a wealth of this stuff, but large parts of it are seemingly moribund, and incomplete after decades or woefully outdated. Wikibooks tried to take up the slack with an "anyone can edit" Guide to Unix and a Linux Guide: * https://en.wikibooks.org/wiki/Guide_to_Unix https://en.wikibooks.org/wiki/Guide_to_Unix * https://en.wikibooks.org/wiki/Linux_Guide https://en.wikibooks.org/wiki/Linux_Guide For examples and doco that works from the basis of what one usually wants to do, then these handbooks and guides are the places to go, not reference manuals.
JdeBP 9y ago
Duplicates https://news.ycombinator.com/item?id=15769046 https://news.ycombinator.com/item?id=15769046
- detaro 9y ago
  please don't point out empty discussions without upvotes as duplicates, unless there are tons of those recently. Reposts are explicitly allowed on HN under these circumstances.
  - JdeBP 9y ago
    At the time that I wrote that this was an empty discussion too. You should bear in mind when things are written.
    - detaro 9y ago
      I don't see how that makes the reference more useful. (I see two purposes for linking to other submissions: point out duplicates that mean the current discussion should be marked dupe (post the link and flag = [dupe] if it's the first comment, otherwise mods add it later), or point other commenters to old but maybe still interesting discussions. Neither case applies when pointing to empty discussions)
harry8 9y ago
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. 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. 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.
- crag_hack 9y ago
  That's just a classic middlebrow dismissal comment. This solution exists. Yours doesn't. This solution is also far more reasonable than yours. Your solution is to somehow land a manpage patch into every project while this is a single project that can be fleshed out by a single sufficiently motivated person.
- exogen 9y ago
  The meat of the project is a crowdsourced database of examples for each program. So naturally there can be multiple clients for that database implemented in various ways. That doesn't seem too complicated. You choose and install one of them. Kind of like how POSIX systems have dozens of pagers, text editors, etc. to choose from. It also seems way less crazy to crowdsource good examples than get each individual program's maintainer to add examples to the official man page (which could take decades to actually get onto people's systems, if they're even accepted), and then still require people to scroll down to the examples section.
  - Spivak 9y ago
    It's less crazy but more error prone. 3rd-party documentation has a tendency of being wrong and out of date quickly. It's not bad but it always needs to be taken with a grain of salt unless you really trust the maintainers of the docs.
kccqzy 9y ago
The main thing about man pages is that it is a "manual": reference material for people who already know the basics. 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.
- __sharp 9y ago
  What I like about this though is it's easy to forget the basic options of a command you haven't used in several months. Having the most common use cases at the top of the man page would save a lot of time than digging through some textbook.
- tnoerlcnt34 9y ago
  Sure, but what usually happens is you sit down at a Unix command line for the first time and have no idea what to do. You ask someone (after seeing that `help` does nothing useful), and they tell you "use 'man' instead of 'help'". And you have no idea why, but you try it and it kind of helps and is better than nothing. You don't have any idea you should `read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books.` (Likewise, you wouldn't know at first to install something like this, either.)
  - dfabulich 9y ago
    I think this is how it used to be, but now people just Google their problems, and typically they get Stack Overflow as a result. Earlier this year, they announced that they have helped over one million developers to exit vim, for example. https://stackoverflow.blog/2017/05/23/stack-overflow-helping-one-million-developers-exit-vim/ https://stackoverflow.blog/2017/05/23/stack-overflow-helping... In my experience, the top-rated SO answer is typically better than the man page, because it answers the specific question I have, rather than listing all of the options in alphabetical order, forcing me to search the page itself for the information I really wanted.
coldsauce 9y ago
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.
nikisweeting 9y ago
There are a bunch of projects like this, check out `cheat` and `bropages` as well.
- omegaham 9y ago
  All I can say with stuff like this is "The more the better."
- shakeel_mohamed 9y ago
  Yep, I love bropages!
menacingly 9y ago
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. 2-3 good examples are what joe blow is looking for when he types "man", and he rarely gets them.
- reikonomusha 9y ago
  This wasn’t always true, when software was less replaceable and felt more valuable. Part of this cake from the fact that software distribution was more difficult. If you ever have purchased a compiler for example you might find yourself interested in everything you can learn about it from the manual. Now developers are trigger-happy Googlers looking for the single salient example atop StackOverflow answers.
  - menacingly 9y ago
    Or, more likely, somewhere in the entire operation of a computer there exists a task or two in which we don't care to specialize.
  - chickenfries 9y ago
    The browser is a much nicer environment for consuming manuals than the terminal.
    - apsdsm 9y ago
      True, unless you're actively working in the terminal, in which case it's kind of a pain to switch to, I'm gonna say.
      - JdeBP 9y ago
        Nonetheless, it was the reasoning that underpinned Daniel Bernstein's slashdoc idea from the turn of the century. * https://cr.yp.to/slashdoc.html https://cr.yp.to/slashdoc.html
    - deleted 9y ago
      [deleted]
begriffs 9y ago
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. 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.
- IgorPartola 9y ago
  By Linux do you mean GNU? Because those are the wordiest and least straightforward. BSDs tend to have excellent documentation as do some individual projects (git), while others (OpenSSL) leave something to be desired. And of course GNU tar is a special little hell. But Linux just happens to run on a GNU userland most of the time so you get those a lot.
  - begriffs 9y ago
    That's a good distinction. Yeah, GNU.
  - wichert 9y ago
    On many Linux systems there are likely to be more non-GNU commands than GNU commands, so I'm not sure your argument fully works here. GNU historically never made man pages: they used Texinfo for documentation, possibly combined with a tool to convert Texinfo to man pages. That shows in the result: an entire manual all joined together in a single unreadably long manual page. The bash man page is a nice example of that. I'm not sure if the use of Texinfo is still a requirement for GNU projects. The verbosity of the generated man pages for GNU software probably did influence a lot of non-GNU Linux software.
    - jwilk 9y ago
      At least in bash 4.4, the manpage and the info page are two different documents. Many GNU manpages are generated with help2man, which causes the opposite problem, i.e. they are too terse. (Also, their typographical quality is often low.)
dilawar 9y ago
Lovely. 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. https://github.com/dilawar/Scripts/blob/master/tldr https://github.com/dilawar/Scripts/blob/master/tldr .
IgorPartola 9y ago
Anyone ever get anything useful out of info pages (vs man pages)? I never quite got what their deal was.
- patrec 9y ago
  A manpage is a glorified README. An info page is a non-horrendous version of a html manual. So to see the appeal, don't compare `man cp` with `info cp`, try some more substantial manual like the emacs manual or python's documentation. Also, emacs is a much better info reader than the standalone program. Info pages are at least an order of magnitude more efficient to navigate than the html documentation that has supplanted them. All the following are fast and a single keypress: - regexp (s)earch (not just the current page, the whole document) - hierarchical navigation ((u)p, (n)ext, (p)revious) - jump to any (i)ndex topic - jump between links/sections (by position: tab, shift-tab, by na(m)e) The main shortcoming of info is no support for styling (or graphics) whatsoever, but if you're used to its efficiency using a mix of googling and clicking to navigate the html equivalent is profoundly frustrating. The closest modern equivalent I know of is Dash.
- mjw1007 9y ago
  As far as the content and organisation goes, they're basically doing everything right that manpages do wrong. They separate tutorial and reference documentation, don't collapse under their own weight when they get large, and have a way to find the documentation for a particular short option. The original standalone terminal reader was pretty poor, though. These days use pinfo or the html version if you're not an emacs user. For a good example, compare `man sed` with `pinfo sed`.
  - jwilk 9y ago
    > have a way to find the documentation for a particular short option How?
    - mjw1007 9y ago
      There's an index, usually a separate one for command-line options. For example in the sed info pages it's under "Command and Option Index" at the bottom of the top-level menu. And, at least in the emacs viewer, there's a keyboard shortcut so you can just type something like « i - n » to see the docs for -n.
baddox 9y ago
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.
chao- 9y ago
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." Thus I was never under the delusion that man pages were, or should strive to be, How-To's of some sort. 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.
- dfabulich 9y ago
  The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is fine, and then a list of options in alphabetical order which is almost always the least useful ordering. Categorize the parameters. Juxtapose confusingly similar options. And only then do we get any examples, if any. The examples should have come first, in the synopsis. There's nothing inherently wrong with man pages, but nobody has to follow this tradition. Put real examples in your synopsis and manually sort your options; you'll have a man page that's 20x better than most.
  - pletnes 9y ago
    I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway. man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addition to man pages.
    - deleted 9y ago
      [deleted]
est 9y ago
Oh my, someone please document tc, iptables and ffmpeg.
- agnivade 9y ago
  Maintainer here. iptables and ffmpeg are already there. You are most welcome to send a PR for tc :)
aliahmed 9y ago
Are you looking for hacker? Contact for any hacking such as Facebook Hacking, Whatsapp Hacking, Instagram, Mobile Hacking, Increase credit score, removal of name from criminal record, removal of links from website. Recover Your email passwords, Hack into Bank/Company web site, etc,if you have any hacking contact: incfidelibus@gmail.com
sunstone 9y ago
MAN pages that start with a few of the basic use case examples would be a breath of fresh air.
whitef0x 9y ago
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. 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.
MichaelMoser123 9y ago
why don't they turn man/info pages into a wiki?
- JdeBP 9y ago
  As mentioned elsewhere on this very page (https://news.ycombinator.com/item?id=15780117 https://news.ycombinator.com/item?id=15780117) "they" did; or rather "they" started two guidebooks on a public wiki.
PaulRobinson 9y ago
Hilariously, ITT are lots of comments saying that man is awful, in response to a pot about a "simplified and community-driven" alternative. 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. 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!
- detaro 9y ago
  Have you successfully convinced any distro to deviate from the normal structure of a man page? If not, I don't believe your suggestion is very realistic.
  - carlosrg 9y ago
    "Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.
    - detaro 9y ago
      Most of the criticism here is exactly about how people do not like the structure of man pages for this use case. If the parent suggests contributing to man pages as a fix for these issues, "Respecting the well-known structure of man pages" goes counter to that goal and suggests that solving this issue outside of man pages actually is the better solution.
      - boomlinde 9y ago
        Many of these pages would make fine EXAMPLES sections for the corresponding man pages without compromising the overall structure.
      - Spivak 9y ago
        It's more important that there is convention than that the convention is optimal. If the problem is that manuals aren't user friendly enough to new users and should have more examples of common tasks then they belong in the EXAMPLES section. There's nothing that says you need to stick to the conventional sections either. A TUTORIAL section wouldn't be out of place.
carlosrg 9y ago
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.
- more-coffee 9y ago
  "Description", yes, "Examples", not always; https://linux.die.net/man/1/sed https://linux.die.net/man/1/sed https://linux.die.net/man/1/grep https://linux.die.net/man/1/grep I think the tldr client can be immensely helpful as a quick cheatsheet in daily operations, whereas manpages will remain to be go-to references for those with time and patience to learn all about the tool in question.
  - JdeBP 9y ago
    Only looking at GNU manual pages gives you a wildly incorrect impression of things. * https://news.ycombinator.com/item?id=15780296 https://news.ycombinator.com/item?id=15780296 Try looking at manual pages that are not GNU. * http://nixdoc.net/man-pages/HP-UX/man1/sed.1.html#EXAMPLES http://nixdoc.net/man-pages/HP-UX/man1/sed.1.html#EXAMPLES * https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.cmds5/sed.htm https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.i... * https://www.freebsd.org/cgi/man.cgi?query=sed#EXAMPLES https://www.freebsd.org/cgi/man.cgi?query=sed#EXAMPLES * http://man.openbsd.org/sed#EXAMPLES http://man.openbsd.org/sed#EXAMPLES
DC-3 9y ago
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/). † Unlike `tldr.py`, which requires you to do `tldr find <command>` instead of `tldr <command>`
krock 9y ago
This is great! I was surprised to find that even a stupid cli that I wrote has a tldr page.
exception_e 9y ago
Thank you, TLDR authors for this tool. It solves a real problem and can coexist with traditional man pages. 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. Caveat: Of course, content would have to be packaged locally for offline use.
sethammons 9y ago
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.
sethammons 9y ago
Not a fan of needing npm. Why not provide a binary? Or did I miss that?
- digi_owl 9y ago
  Welcome to the world of webdev, where every damn language has their own snowflake "package manager"...
- agnivade 9y ago
  Maintainer here. You are free to use the C++ or Go or Rust client. Use a binary all you want. Npm is just one client.
gravypod 9y ago
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]. 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. [0] - https://i.imgur.com/qFnvvaU.png https://i.imgur.com/qFnvvaU.png [1] - https://i.imgur.com/usOwgw2.png https://i.imgur.com/usOwgw2.png
- agnivade 9y ago
  Maintainer here. The node client already has autocompletion for OMZ users - https://github.com/tldr-pages/tldr-node-client#zsh https://github.com/tldr-pages/tldr-node-client#zsh. It also supports command search. So you can do `tldr search "compress a folder into a tarball"`. And you will be shown the top 10 matches. Yes, its not exactly autocompletion. It's more of a match to the apropos command.
webreac 9y ago
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. 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.
urmish 9y ago
Sweet. Added this to my bashrc file. tldr() { curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md | less ; }
- explainplease 9y ago
  If you have Pandoc and w3m: curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md | pandoc --from=markdown --to=html | w3m -T text/html
digi_owl 9y ago
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. 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. Then again, man man may be "enlightening"...
bitwize 9y ago
As others have mentioned, the BSD man pages are the gold standard. Man pages should not be "simplified". They should be easy to read, but comprehensive. How comprehensive? I literally learned NetBSD kernel programming by reading man pages. The same with learning how to write X programs two decades ago.
otherflavors 9y ago
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: .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
Annatar 9y ago
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...
xtiansimon 9y 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.

369 points by akras14 9y ago

tar makes a lot more sense if you use long options instead of completely cryptic short ones. tar command I've been using recently (scripted of course): To compress: tar --create --verbose --use-compress-program="pixz" --file foo.tar.xz --directory <bar_dir> . To extract: tar --extract --verbose --use-compress-program "pixz -d" --file foo.tar.xz 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.

gboudrias 9y ago
By the way, at least for the ones I've tried, --extract now figures out the compression algorithm, so --use-compress-program is possibly redundant. With the cryptic short options it's only one letter, but I find it makes it easier to remember a distinct "4-letter scrabble" for creation versus a "3 letter scrabble" for extraction. (For the long options you save a lot of typing!)
- shmerl 9y ago
  tar wouldn't be able to figure out to use pixz instead of xz in this case just using implicit deduction. I don't really type those options, but use some simple wrapper scripts :) Something like pixzcompress / pixzextract. Scripts also take care to differentiate between directory and a single file.
  - imiric 9y ago
    If you're OK with wrapper scripts, take a look at dtrx[0]. It can extract many different formats, so assuming you have the tools already installed, extracting anything can be done with `dtrx <filename>`. [0]: https://brettcsmith.org/2007/dtrx/ https://brettcsmith.org/2007/dtrx/
    - shmerl 9y ago
      Interesting, but pixz is too new for it, plus it looks like it's using extension to determine the type, so it won't work for the same reason as above. The benefit of pixz is much faster compression / decompression.
    - digi_owl 9y ago
      There is also atool. http://www.nongnu.org/atool/ http://www.nongnu.org/atool/
  - gboudrias 9y ago
    Good to know, thanks! :)
- deleted 9y ago
  [deleted]

Xunxi 9y ago

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. Times have changed and I will definitely love to contribute as well as recommend this project.

paulie_a 9y ago
I've been using Linux for twenty years and have maybe spent two hours reading man pages. Man pages seem to be written by engineers that honestly wrote them like it was code. It's dense material and assumes you can decipher it. Since the days of Alta Vista and webcrawler. And even with Google, I skip the first link (man pages) and find a better explanation
IgorPartola 9y ago
Heh. Should have told you to go read the FreeBSD manual. That’s the first OS that made sense to me because of it. I actually ended up translating parts of it to Russian because I enjoyed it so much. NetBSD was the first thing I got running reliably on my ancient hardware. Linux eventually worked but it was process. And man pages don’t explain what the system does at all.
- JdeBP 9y ago
  Of course, as people have pointed out already, a user manual is not a tutorial, and the two are distinct and complementary. This is something that one finds in many spheres, from Microsoft operating systems to Linux ones. One of the things that MSDN and TechNet doco does is have both "X reference" and "using X" sections. Manual pages are reference doco, in this way of organizing things. The BSD worlds put the "using X" doco into what are often called "handbooks" or "guides". * NetBSD Guide: https://netbsd.org/docs/guide/en/ https://netbsd.org/docs/guide/en/ * FreeBSD Handbook: https://freebsd.org/doc/handbook/book.html https://freebsd.org/doc/handbook/book.html * DragonFlyBSD Handbook: https://www.dragonflybsd.org/docs/handbook/ https://www.dragonflybsd.org/docs/handbook/ * TrueOS User Guide: https://www.trueos.org/handbook/trueos.html https://www.trueos.org/handbook/trueos.html * PC-BSD User Guide: http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html http://web.pcbsd.org/doc-archive/10.1.2/html/pcbsd.html (viewable off-line directly in both PDF and HTML forms in /usr/local/share/pcbsd/doc/) Some parts of the Linux world do the same. upstart had the Upstart Cookbook for example: * http://upstart.ubuntu.com/cookbook/ http://upstart.ubuntu.com/cookbook/ My nosh toolset comes with user manual pages for the individual commands, written in DocBook XML as I just mentioned in https://news.ycombinator.com/item?id=15779321 https://news.ycombinator.com/item?id=15779321 , and a nosh Guide. * http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html http://jdebp.eu./Softwares/nosh/guide/tcp-socket-listen.html * http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-socket.html http://jdebp.eu./Softwares/nosh/guide/anatomy-of-regular-soc... * http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatsheet.html http://jdebp.eu./Softwares/nosh/guide/chain-loading-cheatshe... * http://jdebp.eu./Softwares/nosh/guide.html http://jdebp.eu./Softwares/nosh/guide.html The Linux Documentation Project was supposed to contain a wealth of this stuff, but large parts of it are seemingly moribund, and incomplete after decades or woefully outdated. Wikibooks tried to take up the slack with an "anyone can edit" Guide to Unix and a Linux Guide: * https://en.wikibooks.org/wiki/Guide_to_Unix https://en.wikibooks.org/wiki/Guide_to_Unix * https://en.wikibooks.org/wiki/Linux_Guide https://en.wikibooks.org/wiki/Linux_Guide For examples and doco that works from the basis of what one usually wants to do, then these handbooks and guides are the places to go, not reference manuals.

JdeBP 9y ago

Duplicates https://news.ycombinator.com/item?id=15769046 https://news.ycombinator.com/item?id=15769046

detaro 9y ago
please don't point out empty discussions without upvotes as duplicates, unless there are tons of those recently. Reposts are explicitly allowed on HN under these circumstances.
- JdeBP 9y ago
  At the time that I wrote that this was an empty discussion too. You should bear in mind when things are written.
  - detaro 9y ago
    I don't see how that makes the reference more useful. (I see two purposes for linking to other submissions: point out duplicates that mean the current discussion should be marked dupe (post the link and flag = [dupe] if it's the first comment, otherwise mods add it later), or point other commenters to old but maybe still interesting discussions. Neither case applies when pointing to empty discussions)

harry8 9y ago

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. 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. 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.

crag_hack 9y ago
That's just a classic middlebrow dismissal comment. This solution exists. Yours doesn't. This solution is also far more reasonable than yours. Your solution is to somehow land a manpage patch into every project while this is a single project that can be fleshed out by a single sufficiently motivated person.
exogen 9y ago
The meat of the project is a crowdsourced database of examples for each program. So naturally there can be multiple clients for that database implemented in various ways. That doesn't seem too complicated. You choose and install one of them. Kind of like how POSIX systems have dozens of pagers, text editors, etc. to choose from. It also seems way less crazy to crowdsource good examples than get each individual program's maintainer to add examples to the official man page (which could take decades to actually get onto people's systems, if they're even accepted), and then still require people to scroll down to the examples section.
- Spivak 9y ago
  It's less crazy but more error prone. 3rd-party documentation has a tendency of being wrong and out of date quickly. It's not bad but it always needs to be taken with a grain of salt unless you really trust the maintainers of the docs.

kccqzy 9y ago

The main thing about man pages is that it is a "manual": reference material for people who already know the basics. 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.

__sharp 9y ago
What I like about this though is it's easy to forget the basic options of a command you haven't used in several months. Having the most common use cases at the top of the man page would save a lot of time than digging through some textbook.
tnoerlcnt34 9y ago
Sure, but what usually happens is you sit down at a Unix command line for the first time and have no idea what to do. You ask someone (after seeing that `help` does nothing useful), and they tell you "use 'man' instead of 'help'". And you have no idea why, but you try it and it kind of helps and is better than nothing. You don't have any idea you should `read one of the many "Getting Started" or "Quick Guide" or "Beginning XXX" books.` (Likewise, you wouldn't know at first to install something like this, either.)
- dfabulich 9y ago
  I think this is how it used to be, but now people just Google their problems, and typically they get Stack Overflow as a result. Earlier this year, they announced that they have helped over one million developers to exit vim, for example. https://stackoverflow.blog/2017/05/23/stack-overflow-helping-one-million-developers-exit-vim/ https://stackoverflow.blog/2017/05/23/stack-overflow-helping... In my experience, the top-rated SO answer is typically better than the man page, because it answers the specific question I have, rather than listing all of the options in alphabetical order, forcing me to search the page itself for the information I really wanted.

coldsauce 9y ago

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.

nikisweeting 9y ago

There are a bunch of projects like this, check out `cheat` and `bropages` as well.

omegaham 9y ago
All I can say with stuff like this is "The more the better."
shakeel_mohamed 9y ago
Yep, I love bropages!

menacingly 9y ago

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. 2-3 good examples are what joe blow is looking for when he types "man", and he rarely gets them.

reikonomusha 9y ago
This wasn’t always true, when software was less replaceable and felt more valuable. Part of this cake from the fact that software distribution was more difficult. If you ever have purchased a compiler for example you might find yourself interested in everything you can learn about it from the manual. Now developers are trigger-happy Googlers looking for the single salient example atop StackOverflow answers.
- menacingly 9y ago
  Or, more likely, somewhere in the entire operation of a computer there exists a task or two in which we don't care to specialize.
- chickenfries 9y ago
  The browser is a much nicer environment for consuming manuals than the terminal.
  - apsdsm 9y ago
    True, unless you're actively working in the terminal, in which case it's kind of a pain to switch to, I'm gonna say.
    - JdeBP 9y ago
      Nonetheless, it was the reasoning that underpinned Daniel Bernstein's slashdoc idea from the turn of the century. * https://cr.yp.to/slashdoc.html https://cr.yp.to/slashdoc.html
  - deleted 9y ago
    [deleted]

begriffs 9y ago

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. 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.

IgorPartola 9y ago
By Linux do you mean GNU? Because those are the wordiest and least straightforward. BSDs tend to have excellent documentation as do some individual projects (git), while others (OpenSSL) leave something to be desired. And of course GNU tar is a special little hell. But Linux just happens to run on a GNU userland most of the time so you get those a lot.
- begriffs 9y ago
  That's a good distinction. Yeah, GNU.
- wichert 9y ago
  On many Linux systems there are likely to be more non-GNU commands than GNU commands, so I'm not sure your argument fully works here. GNU historically never made man pages: they used Texinfo for documentation, possibly combined with a tool to convert Texinfo to man pages. That shows in the result: an entire manual all joined together in a single unreadably long manual page. The bash man page is a nice example of that. I'm not sure if the use of Texinfo is still a requirement for GNU projects. The verbosity of the generated man pages for GNU software probably did influence a lot of non-GNU Linux software.
  - jwilk 9y ago
    At least in bash 4.4, the manpage and the info page are two different documents. Many GNU manpages are generated with help2man, which causes the opposite problem, i.e. they are too terse. (Also, their typographical quality is often low.)

dilawar 9y ago

Lovely. 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. https://github.com/dilawar/Scripts/blob/master/tldr https://github.com/dilawar/Scripts/blob/master/tldr .

IgorPartola 9y ago

Anyone ever get anything useful out of info pages (vs man pages)? I never quite got what their deal was.

patrec 9y ago
A manpage is a glorified README. An info page is a non-horrendous version of a html manual. So to see the appeal, don't compare `man cp` with `info cp`, try some more substantial manual like the emacs manual or python's documentation. Also, emacs is a much better info reader than the standalone program. Info pages are at least an order of magnitude more efficient to navigate than the html documentation that has supplanted them. All the following are fast and a single keypress: - regexp (s)earch (not just the current page, the whole document) - hierarchical navigation ((u)p, (n)ext, (p)revious) - jump to any (i)ndex topic - jump between links/sections (by position: tab, shift-tab, by na(m)e) The main shortcoming of info is no support for styling (or graphics) whatsoever, but if you're used to its efficiency using a mix of googling and clicking to navigate the html equivalent is profoundly frustrating. The closest modern equivalent I know of is Dash.
mjw1007 9y ago
As far as the content and organisation goes, they're basically doing everything right that manpages do wrong. They separate tutorial and reference documentation, don't collapse under their own weight when they get large, and have a way to find the documentation for a particular short option. The original standalone terminal reader was pretty poor, though. These days use pinfo or the html version if you're not an emacs user. For a good example, compare `man sed` with `pinfo sed`.
- jwilk 9y ago
  > have a way to find the documentation for a particular short option How?
  - mjw1007 9y ago
    There's an index, usually a separate one for command-line options. For example in the sed info pages it's under "Command and Option Index" at the bottom of the top-level menu. And, at least in the emacs viewer, there's a keyboard shortcut so you can just type something like « i - n » to see the docs for -n.

baddox 9y ago

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.

chao- 9y ago

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." Thus I was never under the delusion that man pages were, or should strive to be, How-To's of some sort. 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.

dfabulich 9y ago
The traditional structure of man pages (Synopsis, Description, Options, and maybe Examples at the end) is just Bad. No documentation expert would write doc this way, not even as a reference, say nothing of a tutorial. The synopsis typically lists a bunch of command-line variations with literally no context, not even a line of commentary to tell the difference between the variations. Then comes a description, which is fine, and then a list of options in alphabetical order which is almost always the least useful ordering. Categorize the parameters. Juxtapose confusingly similar options. And only then do we get any examples, if any. The examples should have come first, in the synopsis. There's nothing inherently wrong with man pages, but nobody has to follow this tradition. Put real examples in your synopsis and manually sort your options; you'll have a man page that's 20x better than most.
- pletnes 9y ago
  I disagree. man pages are optimized for time spent. The cryptic synopsis at the top is enough if I’m checking a frequently used command. The examples are at the bottom for newbies, which need to spend some time reading anyway. man pages are not «good documentation», they are there for people who need to quickly figure out how to run a command. Good projects should have tutorials and complete references online in addition to man pages.
  - deleted 9y ago
    [deleted]

est 9y ago

Oh my, someone please document tc, iptables and ffmpeg.

agnivade 9y ago
Maintainer here. iptables and ffmpeg are already there. You are most welcome to send a PR for tc :)

aliahmed 9y ago

Are you looking for hacker? Contact for any hacking such as Facebook Hacking, Whatsapp Hacking, Instagram, Mobile Hacking, Increase credit score, removal of name from criminal record, removal of links from website. Recover Your email passwords, Hack into Bank/Company web site, etc,if you have any hacking contact: incfidelibus@gmail.com

sunstone 9y ago

MAN pages that start with a few of the basic use case examples would be a breath of fresh air.

whitef0x 9y ago

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. 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.

MichaelMoser123 9y ago

why don't they turn man/info pages into a wiki?

JdeBP 9y ago
As mentioned elsewhere on this very page (https://news.ycombinator.com/item?id=15780117 https://news.ycombinator.com/item?id=15780117) "they" did; or rather "they" started two guidebooks on a public wiki.

PaulRobinson 9y ago

Hilariously, ITT are lots of comments saying that man is awful, in response to a pot about a "simplified and community-driven" alternative. 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. 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!

detaro 9y ago
Have you successfully convinced any distro to deviate from the normal structure of a man page? If not, I don't believe your suggestion is very realistic.
- carlosrg 9y ago
  "Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.
  - detaro 9y ago
    Most of the criticism here is exactly about how people do not like the structure of man pages for this use case. If the parent suggests contributing to man pages as a fix for these issues, "Respecting the well-known structure of man pages" goes counter to that goal and suggests that solving this issue outside of man pages actually is the better solution.
    - boomlinde 9y ago
      Many of these pages would make fine EXAMPLES sections for the corresponding man pages without compromising the overall structure.
    - Spivak 9y ago
      It's more important that there is convention than that the convention is optimal. If the problem is that manuals aren't user friendly enough to new users and should have more examples of common tasks then they belong in the EXAMPLES section. There's nothing that says you need to stick to the conventional sections either. A TUTORIAL section wouldn't be out of place.

carlosrg 9y ago

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.

more-coffee 9y ago
"Description", yes, "Examples", not always; https://linux.die.net/man/1/sed https://linux.die.net/man/1/sed https://linux.die.net/man/1/grep https://linux.die.net/man/1/grep I think the tldr client can be immensely helpful as a quick cheatsheet in daily operations, whereas manpages will remain to be go-to references for those with time and patience to learn all about the tool in question.
- JdeBP 9y ago
  Only looking at GNU manual pages gives you a wildly incorrect impression of things. * https://news.ycombinator.com/item?id=15780296 https://news.ycombinator.com/item?id=15780296 Try looking at manual pages that are not GNU. * http://nixdoc.net/man-pages/HP-UX/man1/sed.1.html#EXAMPLES http://nixdoc.net/man-pages/HP-UX/man1/sed.1.html#EXAMPLES * https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.ibm.aix.cmds5/sed.htm https://www.ibm.com/support/knowledgecenter/ssw_aix_71/com.i... * https://www.freebsd.org/cgi/man.cgi?query=sed#EXAMPLES https://www.freebsd.org/cgi/man.cgi?query=sed#EXAMPLES * http://man.openbsd.org/sed#EXAMPLES http://man.openbsd.org/sed#EXAMPLES

DC-3 9y ago

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/). † Unlike `tldr.py`, which requires you to do `tldr find <command>` instead of `tldr <command>`

krock 9y ago

This is great! I was surprised to find that even a stupid cli that I wrote has a tldr page.

exception_e 9y ago

Thank you, TLDR authors for this tool. It solves a real problem and can coexist with traditional man pages. 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. Caveat: Of course, content would have to be packaged locally for offline use.

sethammons 9y ago

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.

sethammons 9y ago

Not a fan of needing npm. Why not provide a binary? Or did I miss that?

digi_owl 9y ago
Welcome to the world of webdev, where every damn language has their own snowflake "package manager"...
agnivade 9y ago
Maintainer here. You are free to use the C++ or Go or Rust client. Use a binary all you want. Npm is just one client.

gravypod 9y ago

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]. 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. [0] - https://i.imgur.com/qFnvvaU.png https://i.imgur.com/qFnvvaU.png [1] - https://i.imgur.com/usOwgw2.png https://i.imgur.com/usOwgw2.png

agnivade 9y ago
Maintainer here. The node client already has autocompletion for OMZ users - https://github.com/tldr-pages/tldr-node-client#zsh https://github.com/tldr-pages/tldr-node-client#zsh. It also supports command search. So you can do `tldr search "compress a folder into a tarball"`. And you will be shown the top 10 matches. Yes, its not exactly autocompletion. It's more of a match to the apropos command.

webreac 9y ago

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. 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.

urmish 9y ago

Sweet. Added this to my bashrc file. tldr() { curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md | less ; }

explainplease 9y ago
If you have Pandoc and w3m: curl -s https://raw.githubusercontent.com/tldr-pages/tldr/master/pages/common/$1.md | pandoc --from=markdown --to=html | w3m -T text/html

digi_owl 9y ago

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. 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. Then again, man man may be "enlightening"...

bitwize 9y ago

As others have mentioned, the BSD man pages are the gold standard. Man pages should not be "simplified". They should be easy to read, but comprehensive. How comprehensive? I literally learned NetBSD kernel programming by reading man pages. The same with learning how to write X programs two decades ago.

otherflavors 9y ago

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: .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

Annatar 9y ago

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...

xtiansimon 9y 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.